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Preface 


This manual provides users of the OpenVMS operating system with detailed 
usage and reference information on mathematics routines supplied in the MTH$ 
facility of the Run-Time Library. 


Run-Time Library routines can be used only in programs written in languages 
that produce native code for the VAX hardware. At present, these languages 
include VAX MACRO and the following compiled high-level languages: 


VAX Ada 

VAX BASIC 
VAX BLISS-32 
VAX C 

VAX COBOL 
VAX COBOL-74 
VAX CORAL 
VAX DIBOL 
VAX FORTRAN 
VAX Pascal 
VAX PL/I 

VAX RPG 

VAX SCAN 


Interpreted languages that can also access Run-Time Library routines include 
VAX DSM and VAX DATATRIEVE. 


Intended Audience 


This manual is intended for system and application programmers who want to 
call Run-Time Library routines. 


Document Structure 


This manual contains two tutorial chapters, two reference sections, and two 
appendixes: 


Chapter 1 is an introductory chapter that provides guidelines on using the 
MTH$ scalar routines. 


Chapter 2 provides guidelines on using the MTH$ vector routines. 


The Scalar MTH$ Reference Section provides detailed reference information 
on each scalar mathematics routine contained in the MTH$ facility of 

the Run-Time Library. The routines in this section are the same as those 
provided in VMS Version 5.5. 


The Vector MTH$ Reference Section provides detailed reference information 
on the BLAS Level 1 (Basic Linear Algebra Subroutines) and FOLR (First 
Order Linear Recurrence) routines. 


Reference information is presented using the documentation format described 
in the OpenVMS Programming Interfaces: Calling a System Routine. Routine 
descriptions are in alphabetical order by routine name. 


e Appendix A lists supported MTH$ routines not included with the routines in 
the Scalar MTH$ Reference Section, because they are rarely used. 


e Appendix B contains all of the vector MTH$ routines that you can call from 
VAX MACRO in one table. | 


Associated Documents 


The Run-Time Library routines are documented in a series of reference manuals. 
A description of how the Run-Time Library routines are accessed is presented in 
OpenVMS Programming Interfaces: Calling a System Routine. A description of 
OpenVMS features and functionality available through calls to the MTH$ Run- 
Time Library appears in OpenVMS Programming Concepts Manual. Descriptions 
of the other RTL facilities and their corresponding routines are presented in the 
following books: 


¢ DPML, Digital Portable Mathematics Library 

¢ OpenVMS RTL DECtalk (DTK$) Manual 

© OpenVMS RTL Library (LIB$) Manual 

¢ OpenVMS RTL General Purpose (OTS$) Manual 

¢ OpenVMS RTL Parallel Processing (PPL$) Manual 

¢ OpenVMS RTL Screen Management (SMG$) Manual 
¢ OpenVMS RTL String Manipulation (STR$) Manual 


Application programmers using any language can refer to the Guide to Creating 
OpenVMS Modular Procedures for writing modular and reentrant code. 


High-level language programmers will find additional information on calling 
Run-Time Library routines in their language reference manuals. Additional 
information may also be found in the language user’s guide provided with your 
OpenVMS language software. 


For a complete list and description of the manuals in the OpenVMS 
documentation set, see Overview of OpenVMS Documentation. 


Conventions 


Vili 


In this manual, every use of OpenVMS VAX means the OpenVMS VAX operating 
system. 


The following conventions are also used in this manual: 


Ctrl/x A sequence such as Ctrl/x indicates that you must hold down 
the key labeled Ctrl while you press another key or a pointing 
device button. 


PF1 x A sequence such as PF1 x indicates that you must first press 
and release the key labeled PF1, then press and release 
another key or a pointing device button. 


GOLD x 


[ ] 


{ } 


boldface text 


italic text 


UPPERCASE TEXT 


numbers 


A sequence such as GOLD «x indicates that you must first press 
and release the key defined GOLD, then press and release 
another key. GOLD key sequences can also have a slash (/), 
dash (-), or underscore (_) as a delimiter in EVE commands. 


In examples, a key name enclosed in a box indicates that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


A horizontal ellipsis in examples indicates one of the following 
possibilities: 


e Additional optional arguments in a statement have been 
omitted. 


e The preceding item or items can be repeated one or more 
times. 


e Additional parameters, values, or other information can be 
entered. 


A vertical ellipsis indicates the omission of items from a code 
example or command format; the items are omitted because 
they are not important to the topic being discussed. 


In format descriptions, parentheses indicate that, if you 
choose more than one option, you must enclose the choices 
in parentheses. 


In format descriptions, brackets indicate optional elements. 
You can choose one, none, or all of the options. (Brackets are 
not optional, however, in the syntax of a directory name in 
an OpenVMS file specification, or in the syntax of a substring 
specification in an assignment statement. ) 


In format descriptions, braces surround a required choice of 
options; you must choose one of the options listed. 


Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason. 


Boldface text is also used to show user input in Bookreader 
versions of the manual. 


Italic text emphasizes important information, indicates 
variables, and indicates complete titles of manuals. Italic 
text also represents information that can vary in system 
messages (for example, Internal error number), command lines 
(for example, /PRODUCER=name), and command parameters 
in text. 


Uppercase text indicates a command, the name of a routine, 
the name of a file, or the abbreviation for a system privilege. 


A hyphen in code examples indicates that additional 
arguments to the request are provided on the line that follows. 


All numbers in text are assumed to be decimal, unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 





Introduction to MTH$ 


The Run-Time Library mathematics routines may be called to perform a wide 
variety of computations including the following: 


e Floating-point trigonometric function evaluation 
e Exponentiation 

° Complex function evaluation 

e Complex exponentiation 

° Miscellaneous function evaluation 


The OTS$ facility provides additional language-independent arithmetic support 
routines. 


This introduction to Run-Time Library mathematics routines includes examples 
of how to call mathematics routines from BASIC, COBOL, FORTRAN, MACRO, 
Pascal, PL/I, and Ada. 


1.1 Entry Point Names 


The names of the mathematics routines are formed by adding the MTH$ prefix to 
the function names. 


When function arguments and returned values are of the same data type, the 
first letter of the name indicates this data type. When function arguments and 
returned values are of different data types, the first letter indicates the data 
type of the returned value, and the second letter indicates the data type of the 
argument(s). 


The letters used as data type prefixes are listed below. 


Letter Data Type 


I Word 

J Longword 

D D_floating 

G G_floating 

H H_floating 

C F floating complex 
CD D_floating complex 
CG G_fioating complex 


Generally, F-floating data types have no letter designation. For example, 
MTH$SIN returns an F-floating value of the sine of an F-floating argument and 
MTH$DSIN returns a D-floating value of the sine of a D-floating argument. 
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However, in some of the miscellaneous functions, F-floating data types are 
referenced by the letter designation A. 


1.2 Calling Conventions 


For calling conventions specific to the MTH$ vector routines, refer to Chapter 2. 


All calls to mathematics routines, as described in the FORMAT section of 
each routine, accept arguments passed by reference. JSB entry points accept 
arguments passed by value. 


All mathematics routines return values in RO or RO/R1 except those routines for 
which the values cannot fit in 64 bits. D-floating complex, G-floating complex, 
and H-floating values are data structures which are larger than 64 bits. Routines 
returning values that cannot fit in registers RO/R1 return their function values 
into the first argument in the argument list. 


The notation JSB MTH$NAME_Rn, where n is the highest register number 
referenced, indicates that an equivalent JSB entry point is available. Registers 
RO:Rn are not preserved. 


Routines with JSB entry points accept a single argument in RO:Rm, where m, 
which is defined in the following table, is dependent on the data type. 


Data Type m 
F floating 0 
D_floating 1 
G_floating 1 
H_floating 3 


A routine returning one value returns it to registers RO:Rm. 


When a routine returns two values (for example, MTH$SINCOS), the first value 
is returned in RO:Rm and the second value is returned in (R<m+1>:R<2*m+1>). 


Note that for routines returning a single value, n>=m. For routines returning 
two values, n>=2*m + 1. 


In general, CALL entry points for mathematics routines do the following: 
e Disable floating-point underflow 

e Enable integer overflow 

e Cause no floating-point overflow or other arithmetic traps or faults 

e Preserve all other enabled operations across the CALL 


JSB entry points execute in the context of the caller with the enable operations 
as set by the caller. Since the routines do not cause arithmetic traps or faults, 
their operation is not affected by the setting of the arithmetic trap enables, except 
as noted. 


For more detailed information on CALL and JSB entry points, refer to the 
OpenVMS Programming Interfaces: Calling a System Routine. 
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1.3 Algorithms 


For those mathematics routines having corresponding algorithms, the complete 
algorithm can be found in the Description section of the routine description 
appearing in the MTH$ Reference Section of this manual. 


1.4 Condition Handling 


Error conditions are indicated by using the VAX signaling mechanism. The VAX 
signaling mechanism signals all conditions in mathematics routines as SEVERE 
by calling LIB$SIGNAL. When a SEVERE error is signaled, the default handler 
causes the image to exit after printing an error message. A user-established 
condition handler can be written to cause execution to continue at the point of the 
error by returning SS$_CONTINUE. A mathematics routine returns to its caller 
after the contents of RO/R1 have been restored from the mechanism argument 
vector CHF$L_MCH_SAVRO/R1. Thus, the user-established handler should 
correct CHF$L_MCH_ SAVR0O/R1 to the desired function value to be returned to 
the caller of the mathematics routine. 


D-floating complex, G-floating complex, and H-floating values cannot be corrected 
with a user-established condition handler, because R2/R3 is not available in the 
mechanism argument vector. 


Note that it is more reliable to correct RO and R1 to resemble RO and R1 ofa 
double-precision floating-point value. A double-precision floating-point value 
correction works for both single- and double-precision values. 


If the correction is not performed, the floating-point reserved operand —0.0 is 
returned. A floating-point reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Accessing the floating-point reserved 
operand will cause a reserved operand fault. See the OpenVMS RTL Library 
(LIB$) Manual for a complete description of how to write user condition handlers 
for SEVERE errors. 


A few mathematics routines signal floating underflow if the calling program (JSB 
or CALL) has enabled floating underflow faults or traps. 


All mathematics routines access input arguments and the real and imaginary 
parts of complex numbers using floating-point instructions. Therefore, a reserved 
operand fault can occur in any mathematics routine. 


1.5 Complex Numbers 


A complex number y is defined as an ordered pair of real numbers r and i, where 
r is the real part and i is the imaginary part of the complex number. 


y=(r,i) 
OpenVMS supports three floating-point complex types: F-floating complex, 
D-floating complex, and G-floating complex. There is no H-floating complex data 


_ type. 


Run-Time Library mathematics routines that use complex arguments require a 
pointer to a structure containing two x-floating values to be passed by reference 
for each argument. The first x-floating value contains r, the real part of the 
complex number. The second x-floating value contains i, the imaginary part of 
the complex number. Similarly, Run-Time Library mathematics routines that 
return complex function values return two x-floating values. Some Language 
Independent Support (OTS$) routines also calculate complex functions. 


Introduction to MTH$ 
1.5 Complex Numbers 


Note that complex functions have no JSB entry points. 


1.6 Mathematics Routines Not Documented in the MTH$ Reference 
Section 


The mathematics routines in Table 1-1 are not found in the reference section of 
this manual. Instead, their entry points and argument information are listed in 
Appendix A of this manual. 


A reserved operand fault can occur for any floating-point input argument in 
any mathematics routine. Other condition values signaled by each mathematics 
routine are indicated in the footnotes. 


Table 1-1 Additional Mathematics Routines 
Entry Point Function 


Absolute Value Routines 


MTH$ABS F-floating absolute value 
MTH$DABS D-floating absolute value 
MTH$GABS G-floating absolute value 
MTH$HABS H-floating absolute value’ 
MTH$IIABS Word absolute value? 
MTH$JIABS Longword absolute value’ 


Bitwise AND Operator Routines 


MTHSITAND Bitwise AND of two word arguments 
MTH$JIAND Bitwise AND of two longword arguments 


F-floating Conversion Routines 


MTH$DBLE Convert F-floating to D-floating (exact) 
MTH$GDBLE Convert F-floating to G-floating (exact) 
MTH$IIFIX Convert F-floating to word (truncated)? 
MTH$JIFIX Convert F-floating to longword (truncated)? 


1Returns value to the first argument; value exceeds 64 bits. 


2Tnteger overflow exceptions can occur. 
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Table 1-1 (Cont.) Additional Mathematics Routines 
Entry Point Function 


Floating-Point Positive Difference Routines 


MTH$DIM Positive difference of two F-floating arguments? 
MTH$DDIM Positive difference of two D-floating arguments? 
MTH$GDIM Positive difference of two G-floating arguments? 
MTH$HDIM Positive difference of two H-floating arguments** 
MTHS$IIDIM Positive difference of two word arguments” 
MTH$JIDIM Positive difference of two longword arguments” 


Bitwise Exclusive OR Operator Routines 


MTH$IIEOR Bitwise exclusive OR of two word arguments 
MTH$JIEOR Bitwise exclusive OR of two longword arguments 


Integer to Floating-Point Conversion Routines 


MTHS$FLOATI Convert word to F-floating (exact) 
MTH$DFLOTI Convert word to D-floating (exact) 
MTH$GFLOTI Convert word to G-floating (exact) 
MTH$FLOATJ Convert longword to F-floating (rounded) 
MTH$DFLOTJ Convert longword to D-floating (exact) 
MTH$GFLOTJ Convert longword to G-floating (exact) 


Conversion to Greatest Floating-Point Integer Routines 


MTH$FLOOR Convert F-floating to greatest F-floating integer 
MTH$DFLOOR Convert D-floating to greatest D-floating integer 
MTH$GFLOOR Convert G-floating to greatest G-floating integer 
MTH$HFLOOR Convert H-floating to greatest H-floating integer’ 


1Returns value to the first argument; value exceeds 64 bits. 
2Integer overflow exceptions can occur. 


3Floating-point overflow exceptions can occur. 
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Table 1-1 (Cont.) Additional Mathematics Routines 
Entry Point Function 


Floating-Point Truncation Routines 


MTH$AINT Convert F-floating to truncated F-floating 
MTH$IINT Convert F-floating to truncated word? 
MTH$JINT Convert F-floating to truncated longword? 
MTH$DINT Convert D-fioating to truncated D-floating 
MTHS$IIDINT Convert D-floating to truncated word? 
MTH$JIDINT Convert D-floating to truncated longword? 
MTH$GINT Convert G-floating to truncated G-floating 
MTH$IIGINT Convert G-floating to truncated word? 
MTH$JIGINT Convert G-floating to truncated longword” 
MTH$HINT Convert H-floating to truncated H-floating! 
MTH$ITHINT Convert H-floating to truncated word? 
MTH$JIHINT Convert H-floating to truncated longword? 


Bitwise Inclusive OR Operator Routines 


MTH$IIOR 
MTH$JIOR 


Maximum Value Routines 


Bitwise inclusive OR of two word arguments 


Bitwise inclusive OR of two longword arguments 


F-floating maximum of n word arguments 


MTH$AIMAX0 

MTH$AJMAXO F-floating maximum of n longword arguments 
MTH$IMAX0 Word maximum of n word arguments 
MTH$JMAX0O Longword maximum of n longword arguments 
MTH$AMAX1 F-floating maximum of n F-floating arguments 
MTH$DMAX1 D-floating maximum of n D-floating arguments 
MTH$GMAX1 G-floating maximum of n G-floating arguments 
MTH$HMAX1 H-floating maximum of n H-floating arguments? 
MTH$IMAX1 Word maximum of n F-floating arguments” 
MTH$JMAX1 Longword maximum of n F-floating arguments? 


TReturns value to the first argument; value exceeds 64 bits. 


2Integer overflow exceptions can occur. 
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Table 1-1 (Cont.) Additional Mathematics Routines 


Entry Point 


Minimum Value Routines 


MTH$AIMINO 
MTH$AJMINO 
MTH$IMINO 
MTH$JMINO 
MTH$AMIN1 
MTH$DMIN1 
MTH$GMIN1 
MTH$HMIN1 
MTH$IMIN1 
MTH$JMIN1 


Remainder Routines 


MTH$AMOD 
MTH$DMOD 
MTH$GMOD 
MTH$HMOD 
MTH$IMOD 
MTH$JMOD 


Function 


F-floating minimum of n word arguments 
F-floating minimum of n longword arguments 
Word minimum of n word arguments 

Longword minimum of n longword arguments 
F-floating minimum of n F-floating arguments 
D-floating minimum of n D-floating arguments 
G-floating minimum of n G-floating arguments 
H-floating minimum of n H-floating arguments? 
Word minimum of n F-floating arguments” 


Longword minimum of n F-floating arguments? 


Remainder of two F-floating arguments, arg1/arg2°° 
Remainder of two D-floating arguments, arg1/arg2°° 
Remainder of two G-floating arguments, arg1/arg2° 
Remainder of two H-floating arguments, arg1/arg2*? 
Remainder of two word arguments, argl/arg2° 


Remainder of two longword arguments, arg1/arg2” 


Floating-Point Conversion to Nearest Value Routines 


MTH$ANINT 
MTH$ININT 
MTH$JNINT 
MTH$DNINT 
MTH$IDNNT 
MTH$JIDNNT 
MTH$GNINT 
MTH$HIGNNT 
MTH$JIGNNT 


Convert F-floating to nearest F-floating integer 
Convert F-floating to nearest word integer” 
Convert F-floating to nearest longword integer? 
Convert D-floating to nearest D-floating integer 
Convert D-floating to nearest word integer” 
Convert D-floating to nearest longword integer” 
Convert G-floating to nearest G-floating integer 
Convert G-floating to nearest word integer” 


Convert G-floating to nearest longword integer” 


1Returns value to the first argument; value exceeds 64 bits. 


2Integer overflow exceptions can occur. 


3Floating-point overflow exceptions can occur. 


“Divide-by-zero exceptions can occur. 


6Floating-point underflow exceptions are signaled. 
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Table 1-1 (Cont.) Additional Mathematics Routines 


Entry Point Function 

MTH$HNINT Convert H-floating to nearest H-floating integer’ 
MTH$IIHNNT Convert H-floating to nearest word integer” 
MTH$JIHNNT Convert H-floating to nearest longword integer 


Bitwise Complement Operator Routines 

MTH$INOT Bitwise complement of word argument 
MTH$JNOT Bitwise complement of longword argument 
Floating-Point Multiplication Routines 

MTH$DPROD D-floating product of two F-floating arguments” 
MTH$GPROD G-floating product of two F-floating arguments 
Bitwise Shift Operator Routines 

MTH$IISHFT Bitwise shift of word 


MTH$JISHFT Bitwise shift of longword 


Floating-Point Sign Function Routines 


MTH$SGN F- or D-floating sign function 

MTH$SIGN F-floating transfer of sign of y to sign of x 
MTH$DSIGN D-floating transfer of sign of y to sign of x 
MTH$GSIGN G-floating transfer of sign of y to sign of x 
MTH$HSIGN H-floating transfer of sign of y to sign of x’ 
MTH$IISIGN Word transfer of sign of y to sign of x 
MTH$JISIGN Longword transfer of sign of y to sign of x 


1Returns value to the first argument; value exceeds 64 bits. 
2Integer overflow exceptions can occur. 


3Floating-point overflow exceptions can occur. 
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Table 1-1 (Cont.) Additional Mathematics Routines 


Entry Point Function 


Conversion of Double to Single Floating-Point Routines 


MTH$SNGL Convert D-floating to F-floating (rounded)? 
MTH$SNGLG Convert G-floating to F-floating (rounded)** 


3Floating-point overflow exceptions can occur. 
4Floating-point underflow exceptions can occur. 


1.7 Examples of Calls to Run-Time Library Mathematics Routines 


1.7.1 BASIC Example 


The following BASIC program uses the H-floating data type. BASIC also supports 
the D-floating, F-floating, and G-floating data types, but does not support the 
complex data types. 


10 


it 
! Sample program to demonstrate a call to MTHSHEXP from BASIC. 


i 
EXTERNAL SUB MTHSHEXP ( HFLOAT, HFLOAT ) 


DECLARE HFLOAT X,Y ! X and Y are H-floating 
DIGITSS = ‘Fee HFT RHTEREER TERETE EEE ET EE EEE EE 
X = '1.2345678901234567891234567892'H 

CALL MTHSHEXP (Y,X) 

AS = 'MTHSHEXP of ' + DIGITSS + ' is ' + DIGITSS 
PRINT USING AS, X, Y 

END 


The output from this program is as follows: 


MTHSHEXP of 1.234567890123456789123456789200000 
is 3.436893084346008004973301321342110 


1.7.2 COBOL Example 


The following COBOL program uses the F-floating and D-floating data types. 
COBOL does not support the G-floating and H-floating data types or the complex 
data types. 


This COBOL program calls MTH$EXP and MTH$DEXP. 
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IDENTIFICATION DIVISION. 
PROGRAM-ID. FLOATING POINT. 
x 


* Calls MTHSEXP using a Floating Point data type. 
* Calls MTHSDEXP using a Double Floating Point data type. 
* 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 FLOAT PT COMP-1. 
01 ANSWER F COMP-1. 
01 DOUBLE PT  COMP-2. 
01 ANSWER D COMP~2. 
PROCEDURE DIVISION. 
PO. 
MOVE 12.34 TO FLOAT PT. 
MOVE 3.456 TO DOUBLE PT. 


CALL "MTHSEXP" USING BY REFERENCE FLOAT PT GIVING ANSWER F. 
DISPLAY " MTHSEXP. of ", FLOAT PT CONVERSION, " is ", 
ANSWER_F CONVERSION. 


CALL "MTHSDEXP" USING BY REFERENCE DOUBLE PT GIVING ANSWER_D. 
DISPLAY " MTHSDEXP of ", DOUBLE PT CONVERSION, " is ", 

ANSWER D CONVERSION. 
STOP RUN. 


The output from this example program is as follows: 


MTHSEXP of 1.234000E+01 is 2.286620E+05 
MTHSDEXP of 3.456000000000000E+00 is 
3.168996280537917E+01 


1.7.3 FORTRAN Examples 
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The first FORTRAN program below uses the G-floating data type. The second 
FORTRAN program below uses the H-floating data type. The third FORTRAN 
program below uses the F-floating complex data type. FORTRAN supports the 
four floating data types and the three complex data types. 


1:, CF 

C This FORTRAN program computes the log base 2 of x, log2(x) in 
C G-floating double precision by using the RTL routine MTHS$GLOG2. 
C 
C Declare X and Y and MTHSGLOG2 as double precision values. 

C 

C MTHS$GLOG2 will return a double precision value to variable Y. 
C- 

REAL*8 X, Y, MTHSGLOG2 

X = 16.0 

Y = MTHS$GLOG2(X) 

WRITE (6,1) X, Y | 

1 FORMAT (‘ MTHSGLOG2(’,F4.1,’) is ',F4.1) 

END 


The output generated by the preceding program is as follows: 
MTHSGLOG2(16.0) is 4.0 
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+ 


This FORTRAN program computes the log base 2 of x, log2(x) in 
H-floating precision by using the RTL routine MTHSHLOG2. 


Declare X and Y and MTHSGLOG2 as REAL*16 values. 


MTHSHLOG2 will return a REAL*16 value to variable Y. 


AATANAHAANQ 


REAL*16 X, Y 
= 16.12345678901234567890123456789 
CALL MTHSHLOG2(Y, X) 
WRITE (6,1) X, Y 
1 FORMAT (' MTHSHLOG2(',F30.27,') is ',F30.28) 
END 


The output generated by the preceding program is as follows: 
MTHSHLOG2 (16.123456789012345678901234568) is 4.0110891785623860194931388310 


+ 


This FORTRAN example raises a complex base to 
a NONNEGATIVE integer power using OTSSPOWCJ. 


Declare 21, 22, 23, and OTSSPOWCJ as complex values. 
Then OTSSPOWCJ returns the complex result of 

Z1**Z2: 23 = OTSSPOWCI(Z1,22), 

where Z1 and 22 are passed by value. 


AARAQAAMRARQA 


COMPLEX 21,23,OTSSPOWCJ 
INTEGER 22 


C Generate a complex base. 
C= 
= (2.0,3.0) 
C+ 
C Generate an integer power. 
Cu 
Z2 = 2 
C+ 
C Compute the complex value of 21**2Z2. 
C- 
Z3 = OTSSPOWCJ( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), %VAL(Z2)) 
TYPE 1,21,22,23 
i FORMAT ( ' The value of (',F10.8,',',F11.8,')**',I1,' is 
+. (Pll Oa! Pll seg ye") 
END 


The output generated by the preceding FORTRAN program is as follows: 


The value of (2.00000000, 3.00000000)**2 is 
(-5.00000000, 12.00000000). 
1.7.4 MACRO Examples 


MACRO and BLISS support JSB entry points as well as CALLS and CALLG 
entry points. Both MACRO and BLISS support the four floating data types and 
the three complex data types. 


The following MACRO programs show the use of the CALLS and CALLG 
instructions, as well as JSB entry points. 
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TITLE EXAMPLE JSB 


-+ 
f 
; This example calls MTHSDEXP by using a MACRO JSB command. 
+ The JSB command expects RO/R1 to contain the quadword input value X. 
- The result of the JSB will be located in RO/RI1. 
f 
~EXTRN MTHSDEXP R6 *MTHSDEXP is an external routine. 
.PSECT DATA, PIC, EXE, NOWRT 
Xs »~DOUBLE 2.0 * X is 2.0 
~ENTRY EXAMPLE JSB, “M<> 
MOVO xX, RO + X is in registers RO and Rl 
JSB G*MTHSDEXP R6 ; The result is returned in RO/R1. 
RET 


-END EXAMPLE JSB 


This MACRO program generates the following output: 


RQ <-- 732541EC 
Rl <-- ED6EC6A6 


That is, MTHSDEXP(2) is 7.3890560989306502 


-TITLE EXAMPLE CALLG 


This example calls MTHS$HEXP by using a MACRO CALLG command. 

The CALLG command expects that the address of the return value 

Y, the address of the input value X, and the argument count 2 be 
stored in memory; this program stores this information in ARGUMENTS. 
The result of the CALLG will be located in RO/R1. 


=e “Se “=e =8 “=6 “= “=O 


~EXTRN MTHSHEXP + MTHSHEXP is an external routine. 
~PSECT DATA, PIC, EXE, WRT 

ARGUMENTS: 
-LONG 2 The CALLG will use two arguments. 


tf 
~ADDRESS Y, X * The first argument must be the address 
* receiving the computed value, while 

; the second argument is used to 

; compute exp(X). 

> X = 2.0 

i 


X: .H_FLOATING 2 
> Y is the result, initially set to 0. 


Y: .H FLOATING 0 
ENTRY EXAMPLE G, “M<> 
CALLG ARGUMENTS, G*MTHSHEXP ; CALLG returns the value to Y. 
RET 
END EXAMPLE G 


The output generated by this MACRO program is as follows: 
address of Y <-- D8E64003 


<-- 4DDA4B8D 
<-- 3A3BDCC3 
<-- B68BA206 


That is, MTHSHEXP of 2.0 returns 
7.38905609893065022723042746057501 
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TITLE EXAMPLE CALLS 


° + 
f 
* This example calls MTHSHEXP by using the MACRO CALLS command. 
; The CALLS command expects the SP to contain the H-floating address of 
; the return value, the address of the input argument X, and the argument 
; count 2. The result of the CALLS will be located in registers RO-R3. 
f 
~EXTRN MTHSHEXP + MTHSHEXP is an external routine. 
»PSECT DATA, PIC, EXE, WRT 
Y: »H FLOATING 0 * Y is the result, initially set to 0. 
X: .H FLOATING 2 > X= 2 
.ENTRY EXAMPLE S, “M<> 
MOVAL X, -(SP) + The address of X is in the SP. 
MOVAL Y, -(SP) + The address of Y is in the SP 
CALLS Y, G*MTHSHEXP ; The value is returned to the address of Y. 
RET 


-END EXAMPLE S 


The output generated by this program is as follows: 
address of Y <-- D8E64003 


<-- 4DDA4B8D 
<-- 3A3BDCC3 
<-- B68BA206 


That is, MTHSHEXP of 2.0 returns 
7.38905609893065022723042746057501 


-TITLE COMPLEX EX1 


+ 


This example calls MTHSCLOG by using a MACRO CALLG command. 

To compute the complex natural logarithm of Z = (2.0,1.0) register 
RO is loaded with 2.0, the real part of Z, and register Rl is loaded 
with 1.0, the imaginary part of Z. The CALLG to MTHSCLOG 

returns the value of the natural logarithm of Z in 

registers RO and Rl. RO gets the real part of Z and Rl 

gets the imaginary part. 


=e "=e =e “SS “= O8 “=O6 “S08 “=e “6 


~EXTRN MTHSCLOG 
~-PSECT DATA, PIC, EXE, NOWRT 
ARGS: .LONG 1 * The CALLG will use one argument. 
»ADDRESS REAL ; The one argument that the CALLG 
* uses is the address of the argument 
- of MTHSCLOG. 
REAL: .FLOAT 2 ; real part of Z is 2.0 
IMAG: .FLOAT 1 ; imaginary part Z is 1.0 
~ENTRY COMPLEX EX1, “M<> 
CALLG ARGS, G*MTHSCLOG; MTHSCLOG returns the real part of the 
* complex natural logarithm in RO and 
* the imaginary part in Rl. 
RET 
-END COMPLEX EX1 


This program generates the following output: 


RQ <--- 02104045 
R1 <--- 63383FED 


That is, MTHSCLOG(2.0,1.0) is 
(0.8047190,0.4636476) 
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~TITLE COMPLEX EX2 


+ 


=e 


This example calls MTH$CLOG by using a MACRO CALLS command. 

To compute the complex natural logarithm of Z = (2.0,1.0) register 
RO is loaded with 2.0, the real part of Z, and register Rl is loaded 
with 1.0, the imaginary part of Z. The CALLS to MTHSCLOG 

returns the value of the natural logarithm of Z in registers R0 

and Rl. RO gets the real part of Z and R1 gets the imaginary 

part. 


=e “se “@ “O68 “6 SS “SO “NO 


~EXTRN MTHSCLOG 
»PSECT DATA, PIC, EXE, NOWRT 
REAL:  .FLOAT 2 * real part of Z is 2.0 
IMAG: ~FLOAT 1 * imaginary part Z is 1.0 
»~ENTRY COMPLEX EX2, “M<> 
MOVAL REAL, -(SP) ; SP <-- address of Z. Real part of Z is 
in @(SP) and imaginary part is in 
@(SP)+4. 
MTHSCLOG return the real part of the 
complex natural logarithm in RO and 
the imaginary part in Rl. 


CALLS #1, G*MTHSCLOG 


me me ™e ue MO 


RET 
» END COMPLEX EX2 


This MACRO example program generates the following output: 


RQ <~--- 0210404E 
Rl <--- 63383FED 


That is, MTHSCLOG(2.0,1.0) is 
(0.8047190,0.4636476) 


1.7.5 Pascal Examples 


The following Pascal programs use the D-floating and H-floating data types. 
Pascal also supports the F-floating and G-floating data types. Pascal does not 
support the complex data types, however. 
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1. 


{+} 
{ Sample program to demonstrate a call to MTHSDEXP from PASCAL. 


oe 
PROGRAM CALL MTHSDEXP (OUTPUT); 


{+} 
{ Declare variables used by this program. 
{=} 
VAR 
X : DOUBLE := 3.456; { X,Y are D-floating unless overridden } 
Y : DOUBLE; { with /DOUBLE qualifier on compilation } 
{t+} . 
{ Declare the RTL routine used by this program. 
12) 
[ EXTERNAL, ASYNCHRONOUS] FUNCTION MTHSDEXP (VAR value : DOUBLE) : DOUBLE; EXTERN; 
BEGIN 


Y := MTHSDEXP (x); 
WRITELN (‘’MTHSDEXP of ', X:5:3, ' is ', Y:20:16); 
END. 
The output generated by this Pascal program is as follows: 


MTHSDEXP of 3.456 is 31.6899656462382318 


2. 
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{+} 

{ Sample program to demonstrate a call to MTHSHEXP from PASCAL. 

{-} 

PROGRAM CALL MTHSHEXP (OUTPUT) ; 

{+} . 

{ Declare variables used by this program. 

as 

VAR 
X : QUADRUPLE := 1.2345678901234567891234567892; { X is H-floating } 
Y : QUADRUPLE; { Y is H-floating } 

{+} 

{ Declare the RTL routine used by this program. 

t=] 

[EXTERNAL, ASYNCHRONOUS] PROCEDURE MTHSHEXP (VAR h exp : QUADRUPLE; 

value : QUADRUPLE); EXTERN; 


BEGIN 

MTHSHEXP (Y,X); 

WRITELN (‘MTHSHEXP of ', X:30:28, ' is ', Y¥:35:33); 
END. 


This Pascal program generates the following output: 


MTHSDEXP of 3.456 is 31.6899656462382318 


1.7.6 PL/I Examples 
The following PL/I programs use the D-floating and H-floating data types to test 
entry points. PL/I also supports the F-floating and G-floating data types. PL/I 
does not support the complex data types, however. 


1. 


/* 
* 


* This program tests a MTHSD entry point 
*k 

*/ 

TEST: PROC OPTIONS (MAIN) ; 


DCL (MTHSDEXP) 

ENTRY (FLOAT(53)) RETURNS (FLOAT(53)); 
DCL OPERAND FLOAT(53); 
DCL RESULT FLOAT(53); 


/*** Begin test ***/ 
OPERAND = 3.456; 
RESULT = MTH$DEXP(OPERAND); 
PUT EDIT ('MTHSDEXP of ', OPERAND, ' is ', 
RESULT) (A(12),F(5,3),A(4) ,F(20,15)); 


END TEST; 


The output generated by this PL/I program is as follows: 
MTHSDEXP of 3.456 is 31.689962805379165 
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2. /* 
* * 
* This program tests a MTHS$H entry point. * 
* Note that in the PL/I statement below, the /G-float switch * 
* is needed to compile both G- and H-floating point MTHS routines. */ 


TEST: PROC OPTIONS (MAIN) ; 


DCL (MTH$HEXP) 

ENTRY (FLOAT (113), FLOAT (113)) ; 
DCL OPERAND FLOAT (113); 
DCL RESULT FLOAT (113); 


/*** Begin test ***/ 
OPERAND = 1.234578901234567891234567892; 
CALL MTHSHEXP (RESULT, OPERAND) ; 
PUT EDIT (‘MTHSHEXP of ', OPERAND, ' is ', 
RESULT) (A(12),F(29,27),A(4) ,F(29,27)); 


END TEST; 


To run this program, use the following DCL commands: 


$ PLI/G FLOAT EXAMPLE 
$ LINK EXAMPLE 
$ RUN EXAMPLE 


This program generates the following output: 


MTHSHEXP of 1.234578901234567891234567892 is 
3.436930928565989790506225633 


1.7.7 Ada Example 
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The following Ada program demonstrates the use of MTH$ routines in a manner 
that an actual program might use. The program performs the following steps: 


e Reads a floating-point number from the terminal 

¢ Calls MTH$SQRT to obtain the square root of the value read 

¢ Calls MTH$JNINT to find the nearest integer of the square root 
e Displays the result 


This example runs on VAX Ada Version 2.0 or later. 


-- This Ada program calls the MTHSSQRT and MTHSJNINT routines. 
with FLOAT MATH LIB; 
~- Package FLOAT MATH LIB is an instantiation of the generic package 
-- MATH LIB for the FLOAT datatype. This package provides the most 
-- common mathematical functions (SQRT, SIN, COS, etc.) in an easy 
-- to use fashion. An added benefit is that the VAX Ada compiler 
-- will use the faster JSB interface for these routines. 
with MTH; 
-- Package MTH defines all the MTH$ routines. It should be used when 
-- package MATH LIB is not sufficient. All functions are defined here 
-~ as "valued procedures" for consistency. 
with FLOAT TEXT 10, INTEGER TEXT 10, TEXT I0; 
procedure ADA EXAMPLE is 7 
FLOAT VAL: FLOAT; 
INT VAL: INTEGER; 
begin 
-- Prompt for initial value. 
TEXT IO.PUT ("Enter value: "); 
FLOAT TEXT I0.GET (FLOAT VAL); 
TEXT IO.NEW LINE; 7 
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-- Take the square root by using the SQRT routine from package 
-- FLOAT MATH LIB. The compiler will use the JSB interface 

-- to MTHSSQRT. 

FLOAT VAL := FLOAT MATH LIB.SQRT (FLOAT VAL); 


-- Find the nearest integer using MTHS$JNINT. Argument names are 
-- the same as those listed for MTHSJNINT in the reference 

-- section of this manual. 

MTH.JNINT (F FLOATING => FLOAT VAL, RESULT => INT VAL); 


-- Write the result. 
TEXT IO.PUT ("Result is: "); 
INTEGER TEXT IO.PUT (INT VAL); 
TEXT IO.NEW LINE; 7 

end ADA EXAMPLE; 


To run this example program, use the following DCL commands: 


$ CREATE/DIR [.ADALIB] 

$ ACS CREATE LIB [.ADALIB] 
$ ACS SET LIB [.ADALIB] 

$ ADA ADA EXAMPLE 

$ ACS LINK ADA EXAMPLE 

$ RUN ADA EXAMPLE 


The preceding Ada example generates the following output: 


Enter value: 42.0 
Result is: 6 
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Vector Routines in MTH$ 


This chapter discusses four sets of routines provided by the RTL MTH$ facility 
that support vector processing. These routines are as follows: 


e Basic Linear Algebra Subroutines (BLAS) Level 1 
e First Order Linear Recurrence (FOLR) routines 
e Vector versions of existing scalar routines 


e Fast-Vector math routines 


2.1 BLAS — Basic Linear Algebra Subroutines Level 1 


The BLAS Level 1 routines perform operations on vectors, such as copying a 
vector to another vector, swapping vectors, and so on. These routines help you 
take advantage of the vector processing speed. BLAS Level 1 routines form an 
integral part of many mathematical libraries such as LINPACK and EISPACK. 
! Because these routines usually occur in the innermost loops of user code, the 
Run-Time Library provides versions of the BLAS Level 1 that are tuned to take 
best advantage of the VAX vector processors. 


Two versions of BLAS Level 1 are provided. To use either of these libraries, link 
in the appropriate shareable image. The libraries are: 


e Scalar BLAS — contained in the shareable image BLASIRTL 


e Vector BLAS (routines that take advantage of vectorization) — contained in 
the shareable image VBLASIRTL 


Note 


To call the scalar BLAS from a program that runs on scalar 
hardware, specify the routine name preceded by BLAS1$ (for example, 
BLAS1$xCOPY). To call the vector BLAS from a program that runs on 
vector hardware, specify the routine name preceded by BLAS1$V (for 
example, BLAS1$VxCOPY). 


This manual describes both the scalar and vector versions of BLAS Level 1, 
but for simplicity the vector prefix (BLAS1$V) is used exclusively. Remember 
to remove the letter V from the routine prefix when you want to call the scalar 
version. 


1 For more information, see Basic Linear Algebra Subprograms for FORTRAN Usage in 
ACM Transactions on Mathematical Software, Vol. 5, No. 3, September 1979. 
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If you are a VAX FORTRAN programmer, do not specify BLAS vector 

routines explicitly. Specify the FORTRAN intrinsic function name only. 

The VAX FORTRAN-HPO compiler will then determine whether the vector 

or scalar version of a BLAS routine should be used. The FORTRAN 
/BLAS=([NOJINLINE,[NOJMAPPED) qualifier controls how the compiler 
processes calls to BLAS Level 1. If /NOBLAS is specified, then all BLAS calls 
are treated as ordinary external routines. The default of INLINE means that 
calls to BLAS Level 1 routines will be treated as known language constructs, and 
VAX object code will be generated to compute the corresponding operations at 
the call site, rather than call a user-supplied routine. If the FORTRAN qualifier 
/VECTOR or /PARALLEL=AUTO is in effect, the generated code for the loops 
may use vector instructions or be decomposed to run on multiple processors. 

If MAPPED is specified, these calls will be treated as calls to the optimized 
implementations of these routines in the BLAS1$ and BLAS1$V portions of the 
MTH$ facility. For more information on the FORTRAN /BLAS qualifier, refer to 
the VAX FORTRAN Performance Guide. 


Ten families of routines form BLAS Level 1. (BLASI$VxCOPY is one family 
of routines, for example.) These routines operate at the vector-vector operation 
level. This means that BLAS Level 1 perform operations on one or two vectors. 
The level of complexity of the computations (in other words, the number of 
operations being performed in a BLAS Level 1 routine) is of the order n (the 
length of the vector). 


Each family of routines in BLAS Level 1 contains routines coded in single 
precision, double precision (D and G formats), single precision complex, and 
double precision complex (D and G formats). BLAS Level 1 can be broadly 
classified into three groups: 


e BLAS1$VxCOPY, BLAS1$VxSWAP, BLAS1$VxSCAL and BLAS1$VxAXPY: 
These routines return vector output(s) for vector inputs. The results of all 
these routines are independent of the order in which the elements of the 
vector are processed. The scalar and vector versions of these routines return 
the same results. 


e¢ BLAS1$VxDOT, BLASI$VIxAMAX, BLASI$VxASUM, and BLASI$VxNRM2: 
These routines are all reduction operations that return a scalar value. The 
results of these routines (except BLAS1$VIxAMAX) are dependent upon the 
order in which the elements of the vector are processed. The scalar and vector 
versions of BLAS1$VxDOT, BLAS1$VxASUM, and BLAS1$VxNRM2 can 
return different results. The scalar and vector versions of BLASI$VIxAMAX 
return the same results. 


¢ BLAS1$VxROTG and BLAS1$VxROT: These routines are used for a 
particular application (plane rotations), unlike the routines in the previous 
two categories. The results of BLASI$VxROTG and BLAS1$VxROT are 
independent of the order in which the elements of the vector are processed. 
The scalar and vector versions of these routines return the same results. 


Table 2-1 lists the functions and corresponding routines of BLAS Level 1. 
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Table 2—1 Functions of BLAS Level 1 


Function 


Copy a vector to 


another vector 


Swap the elements 


of two vectors 


Scale the elements 


of a vector 


Multiply a vector by a 


scalar and add a vector 


Obtain the index of the 
first element of a vector 
having the largest 


absolute value 


Routine 


BLAS1$VSCOPY 
BLAS1$VDCOPY 
BLAS1$VCCOPY 
BLAS1$VZCOPY 


BLAS1$VSSWAP 
BLAS1$VDSWAP 
BLAS1$VCSWAP 
BLAS1$VZSWAP 


BLAS1$VSSCAL 
BLAS1$VDSCAL 
BLAS1$VGSCAL 
BLAS1$VCSCAL 


BLAS1$VCSSCAL 
BLAS1$VZSCAL 


BLAS1$VWSCAL 
BLAS1$VZDSCAL 


BLAS1$VWGSCAL 


BLAS1$VSAXPY 
BLAS1$VDAXPY 
BLAS1$VGAXPY 
BLAS1$VCAXPY 
BLASI$VZAXPY 
BLAS1$VWAXPY 


BLAS1$VISAMAX 
BLAS1$VIDAMAX 
BLAS1$VIGAMAX 
BLAS1$VICAMAX 
BLAS1$VIZAMAX 
BLAS1$VIWAMAX 


Data Type 

Single 

Double (D-floating or G-floating) 
Single complex 


Double complex (D-floating or 
G-floating) 


Single 
Double (D-floating or G-floating) 
Single complex 


Double complex (D-floating or 
G-floating) 


Single 
Double (D-floating) 


Double (G-floating) 


Single complex with complex 
scale 


Single complex with real scale 


Double complex with complex 
scale (D-floating) 


Double complex with complex 
scale (G-floating) 


Double complex with real scale 
(D-floating) 


Double complex with real scale 
(G-floating) 


Single 

Double (D-floating) 

Double (G-floating) 

Single complex 

Double complex (D-floating) 
Double complex (G-floating) 


Single 

Double (D-floating) 

Double (G-floating) 

Single complex 

Double complex (D-floating) 
Double complex (G-floating) 


(continued on next page) 
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Table 2-1 (Cont.) Functions of BLAS Level 1 


Function 


Obtain the sum of the 
absolute values of the 


elements of a vector 


Obtain the inner 


product of two vectors 


Obtain the Euclidean 


norm of the vector 


Generate the elements 


for a Givens plane 


rotation 
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Routine 


BLAS1$VSASUM 
BLAS1$VDASUM 
BLAS1$VGASUM 
BLAS1$VSCASUM 
BLAS1$VDZASUM 
BLAS1$VGWASUM 


BLAS1$VSDOT 
BLAS1$VDDOT 
BLAS1$VGDOT 
BLAS1$VCDOTU 
BLAS1$VCDOTC 
BLAS1$VZDOTU 


BLAS1$VWDOTU 
BLAS1$VZDOTC 


BLAS1$VWDOTC 


BLAS1$VSNRM2 
BLAS1$VDNRM2 
BLAS1$VGNRM2 
BLAS1$VSCNRM2 
BLAS1$VDZNRM2 
BLAS1$VGWNRM2 
BLAS1$VSROTG 
BLAS1$VDROTG 
BLAS1$VGROTG 
BLAS1$VCROTG 
BLAS1$VZROTG 
BLAS1$VWROTG 


Data Type 


Single 

Double (D-floating) 

Double (G-floating) 

Single complex 

Double complex (D-floating) 
Double complex (G-floating) 


Single 

Double (D-floating) 

Double (G-floating) 

Single complex unconjugated 
Single complex conjugated 


Double complex unconjugated 
(D-floating) 


Double complex unconjugated 
(G-floating) 


Double complex conjugated (D- 
floating) 


Double complex conjugated (G- 
floating) 


Single 

Double (D-floating) 

Double (G-floating) 

Single complex 

Double complex (D-floating) 
Double complex (G-floating) 
Single 

Double (D-floating) 

Double (G-floating) 

Single complex 

Double complex (D-floating) 
Double complex (G-floating) 


(continued on next page) 
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Table 2—1 (Cont.) Functions of BLAS Level 1 


Function Routine Data Type 

Apply a Givens plane BLASI$VSROT Single 

rotation BLAS1$VDROT Double (D-floating) 
BLAS1$VGROT Double (G-floating) 
BLAS1$VCSROT Single complex 
BLAS1$VZDROT Double complex (D-floating) 


BLAS1$VWGROT Double complex (G-floating) 


For a detailed description of these routines, refer to the Vector MTH$ Reference 
Section of this manual. 


2.1.1 Using BLAS Level 1 


The following sections provide some guidelines for using BLAS Level 1. 


2.1.1.1 Memory Overlap 
The vector BLAS produces unpredictable results when any element of the input 
argument shares a memory location with an element of the output argument. (An 
exception is a special case found in the BLAS1$VxCOPY routines.) 


The vector BLAS and the scalar BLAS can yield different results when the input 
argument overlaps the output array. 


2.1.1.2 Round-Off Effects 


For some of the routines in BLAS Level 1, the final result is independent of 
the order in which the operations are performed. However, in other cases (for 
example, some of the reduction operations), efficiency dictates that the order of 
operations on a vector machine be different from the natural order of operations. 
Because round-off errors are dependent upon the order in which the operations 
are performed, some of the routines will not return results that are bit-for-bit 
identical to the results obtained by performing the operations in natural order. 


Where performance can be increased by the use of a backup data type, this 
has been done. This is the case for BLASI$SVSNRM2, BLAS1I$VSCNRM2, 
BLAS1$VSROTG, and BLAS1$VCROTG. The use of a backup data type can 
also yield a gain in accuracy over the scalar BLAS. 


2.1.1.3 Underflow and Overflow 


In accordance with LINPACK convention, underflow, when it occurs, is replaced 
by a zero. A system message informs you of overflow. Because the order of 
operations for some routines is different from the natural order, overflow might 
not occur at the same array element in both the scalar and vector versions of the 
routines. 


2.1.1.4 Notational Definitions 


The vector BLAS (except the BLAS1$VxROTG routines) perform operations on 
vectors. These vectors are defined in terms of three quantities: 


e A vector length, specified as n 
e An array or a starting element in an array, specified as x 


e An increment or spacing parameter to indicate the distance in number of 
array elements to skip between successive vector elements, specified as inex 
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Suppose x is a real array of dimension ndim, n is its vector length, and inex is 
the increment used to access the elements of a vector X. The elements of vector 
X, X;,2 = 1,...,n, are stored in x. If inex is greater than or equal to 0, then X; is 
stored in the following location: 

x(1+ (2 — 1) *incz) 

However, if inex is less than 0, then X; is stored in the following location: 

x(1+ (n — 4) « |¢nca]) 

It therefore follows that the following condition must be satisfied: 

ndim>1 + (n — 1) * |tnca| 


A positive value for inex is referred to as forward indexing, and a negative 
value is referred to as backward indexing. A value of zero implies that all of the 
elements of the vector are at the same location, xj. 


Suppose ndim = 20 and n = 5. In this case, inex = 2 implies that X1, X9, Xs, 
X4, and Xs are located in array elements x1, x3, x5, x7, and xo. 


If, however, inex is negative, then Xj, Xo, X3, X4, and Xs are located in array 
elements x9, x7, x5, X3, and xj. In other words, when inex is negative, the 
subscript of x decreases as 7 increases. 


For some of the routines in BLAS Level 1, inex = 0 is not permitted. In the cases 
where a zero value for inex is permitted, it means that x; is broadcast into each 
element of the vector X of length n. 


You can operate on vectors that are embedded in other vectors or matrices by 
choosing a suitable starting point of the vector. For example, if A is an nl by n2 
matrix, its j-th column is referenced with a length of n1, starting point A(1,j), and 
increment 1. Similarly, the i-th row is referenced with a Elenetn of n2, starting 
point AG, 1), and increment nl. 


2.2 FOLR — First Order Linear Recurrence Routines 


The MTH$ FOLR routines provide a vectorized algorithm for the linear 
recurrence relation. A linear recurrence uses the result of a previous pass 
through a loop as an operand for subsequent passes through the loop and 
prevents the vectorization of a loop. 


The only error checking performed by the FOLR routines is for a reserved 
operand. 


There are four families of FOLR routines in the MTH$ facility. Each family 
accepts each of four data types (longword integer, F-floating, D-floating, and 
G-floating). However, all of the arrays you specify in a single FOLR call must be 
of the same data type. 


For a detailed description of these routines, refer to the Vector MTH$ Reference 
Section of this manual. 


2.2.1 FOLR Routine Name Format 


The four families of FOLR routines are as follows: 
¢ MTH$VxFOLRy_MA_V15 

e MTH$VxFOLRy_z_V8 

e MTH$VxFOLRLy_MA_V5 
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¢ MTH$VxFOLRLy_z_V2 


where: 

x = J for longword integer, F for F-floating, D for D-floating, or G for G-floating 
y = P fora positive recursion element, or N for a negative recursion element 

z = M for multiplication, or A for addition 


The FOLR entry points end with _Vn, where n is an integer between 0 and 
15 that denotes the vector registers that the FOLR routine uses. For example, 
MTH$VxFOLRy_z_V8 uses vector registers VO through V8. 


To determine which group of routines you should use, match the task in the left 
column in Table 2-2 that you need the routine to perform with the method of 
storage that you need the routine to employ. The point where these two tasks 
meet shows the FOLR routine you should call. 


Table 2—2 Determining the FOLR Routine You Need 


Tasks Save each iteration in an array Save only last result in a variable 
Multiplication AND MTH$VxFOLRy_MA_V15 MTH$VxFOLRLy_MA_V5 
addition 

Multiplication OR MTH$VxFOLRy_z_V8 MTH$VxFOLRLy_z_V2 

addition | 


2.2.2 Calling a FOLR Routine 


Save the contents of VO through Vn before calling a FOLR routine if you need 

it after the call. The variable n can be 2, 5, 8, or 15, depending on the FOLR 
routine entry point. (The OpenVMS Calling Standard specifies that a called 
procedure may modify all of the vector registers. The FOLR routines modify only 
the vector registers VO through Vn.) 


The MTH$ FOLR routines assume that all of the arrays are of the same data 
type. 


2.3 Vector Versions of Existing Scalar Routines 


Vector forms of many MTH$ routines are provided to support vectorized compiled 
applications. Vector versions of key F-floating, D-floating, and G-floating scalar 
routines employ vector hardware, while maintaining identical results with their 
scalar counterparts. Many of the scalar algorithms have been redesigned to 
ensure identical results and good performance for both the vector and scalar 
versions of each routine. All vectorized routines return bit-for-bit identical results 
as the scalar versions. 


You can call the vector MTH$ routines directly if your program is written in 
VAX MACRO. If you are a FORTRAN programmer, specify the FORTRAN 
intrinsic function name only. The VAX FORTRAN-HPO compiler will then 
determine whether the vector or scalar version of a routine should be used. 


2.3.1 Exceptions 


You should not attempt to recover from an MTH$ vector exception. After an 
MTH$ vector exception, the vector routines cannot continue execution, and 
nonexceptional values might not have been computed. 
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2.3.2 Underflow Detection 


In general, if a vector instruction results in the detection of both a floating 
overflow and a floating underflow, only the overflow will be signaled. 


Some scalar routines check to see if a user has enabled underflow detection. For 
each of those scalar routines, there are two corresponding vector routines: 

one that always enables underflow checking and one that never enables 
underflow checking. (In the latter case, underflows produce a result of zero.) 
The VAX FORTRAN-HPO compiler always chooses the vector version that does 
not signal underflows, unless the user specifies the appropriate VAX FORTRAN- 
HPO compiler switch (the /CHECK=UNDERFLOW qualifier). This ensures that 
the check is performed but does not impair vector performance for those not 
interested in underflow detection. 


2.3.3 Vector Routine Name Format 
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Use one of the formats in Table 2-3 to call (from VAX MACRO) a vector math 
routine that enables underflow signaling. (The E in the routine name means 
enabled underflow signaling.) 


Table 2-3 Vector Routine Format — Underflow Signaling Enabled 


Format Type of Routine 

MTH$VxSAMPLE_E_Ry_Vz Real valued math routine 
MTH$VCxSAMPLE_E_Ry_Vz Complex valued math routine 
OTS$SAMPLEq_E_Ry_Vz Power routine or complex multiply and divide 


Use one of the formats in Table 2—4 to call (from VAX MACRO) a vector math 
routine that does not enable underflow signaling. 


Table 2-4 Vector Routine Format — Underflow Signaling Disabled 


Format Type of Routine 
MTH$VxSAMPLE_Ry_Vz Real valued math routine 
MTH$VCxSAMPLE_Ry_Vz Complex valued math routine 
OTS$SAMPLEq_Ry_Vz Power routine or complex multiply/divide 


In the preceding formats, the following conventions are used: 


The letter A (or blank) for F-floating, D for D-floating, G for G-floating. 


y A number between 0 and 11 (inclusive). Ry means that the scalar registers RO 


through Ry will be used by the routine SAMPLE. You must save these registers. 


z A number between 0 and 15 (inclusive). Vz means that the vector registers VO 
through Vz will be used by the routine SAMPLE. You must save these registers. 


q Two letters denoting the base and power data type, as follows: 


RR F-floating base raised to an F-floating power 
RJ F-floating base raised to a longword power 
DD D-floating base raised to a D-floating power 
DJ D-floating base raised to a longword power 
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GG G-floating base raised to a G-floating power 
GJ G-floating base raised to a longword power 
JJ Longword base raised to a longword power 


2.3.4 Calling a Vector Math Routine 


You can call the vector MTH$ routines directly if your program is written in 


VAX MACRO. 


Note 


If you are a VAX FORTRAN programmer, do not specify the MTH$ vector 
routines explicitly. Specify the FORTRAN intrinsic function name only. 
The VAX FORTRAN-HPO compiler will then determine whether the 
vector or scalar version of a routine should be used. 


In the following examples, keep in mind that vector real arguments are passed 
in VO, V1, and so on, and vector real results are returned in VO. On the other 
hand, vector complex arguments are passed in VO and V1, V2, and V3, and so on. 
Vector complex results are returned in VO and V1. 


Argument Passed Results Returned 
Argument Register Register 
Vector real arguments vo," V1.... VO 
Vector complex arguments VO and V1, V2 and V3.... VO and V1 


Example 1 


The following example shows how to call the vector version of MTH$EXP. Assume 
that you do not want underflows to be signaled, and you need to use the current 
contents of all vector and scalar registers after the invocation. Before you can call 
the vector routine from VAX MACRO, perform the following steps. 


1. Find EXP in the column of scalar names in Appendix B to determine: 
e The full vector routine name: MTH$VEXP_R3_V6 
e How the routine is invoked (CALL or JSB): JSB 


¢ The scalar registers that must be saved: RO through R38 (as specified by 
R3 in MTH$VEXP_R3_V6) 


e The vector registers that must be saved: VO through V6 (as specified by 
V6 in MTH$VEXP_R3_V6) 


e The vector register(s) used to hold the input argument(s): VO 
e The vector register(s) used to hold the output argument(s): VO 


e If there is a vector version that signals underflow (not needed in this 
example) 


Save the scalar registers RO, R1, R2, and R3. 
Save the vector registers V0, V1, V2, V3, V4, V5, and V6. 
Save the vector mask register VMR. 


oS ee 


Save the vector count register VCR. 
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6. Load the vector length register VLR. 

7. Load the vector register VO with the argument for MTH$EXP. 
8. JSB to MTH$VEXP_R3_V6. 

9. Store result in memory. 


10. Restore all scalar and vector registers except for VO. (The results of the "call" 
to MTH$VEXP_R3_V6 are stored in V0.) 


The following MACRO program fragment shows this example. Assume that: 
e V0 through V6 and RO through R3 have been saved. 
e 4 points to a vector of 60 input values. 


e R6 points to the location where the results of MTH$VEXP_R3_V6 will be 
stored. 


e R5 contains the stride in bytes. 


Note that MTH$VEXP_R3_V6 denotes an F-floating data type because there is 
no letter between V and E in the routine name. (For further explanation, refer to 
Section 2.3.3.) The stride (the number of array elements that are skipped) must 
be a multiple of 4 because each F-floating value requires 4 bytes. 


MTVLR #60 * Load VLR 

MOVL #4, R5 » Stride 

VLDL (R4), R5, VO ; Load VO with the actual arguments 
JSB G“MTHSVEXP R3_ V6 * JSB to MTHSVEXP 

VSTL VO, (R6), R5 + Store the results 


Example 2 


The following example demonstrates how to call the vector version of 
OTS$POWDD with a vector base raised to a scalar power. Before you can call the 
vector routine from VAX MACRO, perform the following steps. 


1. Find POWDD (V*) in the column of scalar names in Appendix B to 
determine: 


e The full vector routine name: OTS$VPOWDD RI V8 
¢ How the routine is invoked (CALL or JSB): CALL 


e The scalar registers that must be saved: RO through R1 (as specified by 
R1 in OTS$VPOWDD_R1_V8) 


e The vector registers that must be saved: VO through V8 (as specified by 
V8 in OTS$VPOWDD_R1_V8) 


e The vector register(s) used to hold the input argument(s): VO, RO 
e The vector register(s) used to hold the output argument(s): VO 


e If there is a vector version that signals underflow (not needed in this 
example) 


Save the scalar registers RO and R1. 
Save the vector registers VO, V1, V2, V3, V4, V5, V6, V7, and V8. 
Save the vector mask register VMR. 
Save the vector count register VCR. 


Load the vector length register VLR. 


2 Sk ee ees 


Vector Routines in MTHS 
2.3 Vector Versions of Existing Scalar Routines 


7. Load the vector register VO and the scalar register RO with the arguments for 
OTS$POWDD. 


Call OTS$VPOWDD_R1_V8. 
Store result in memory. 


10. Restore all scalar and vector registers except for VO. (The results of the call 
to OTS$VPOWDD_R1_V8 are stored in V0.) 


The following MACRO program fragment shows how to call OTS$VPOWDD_R1_ 
V8 to compute the result of raising 60 values to the power P. Assume that: 


e VO through V8 and RO and R1 have been saved. 

¢ R4 points to the vector of 60 input base values. 

e RO and R1 contain the D-floating value P. 

e R6 points to the location where the results will be stored. 
e R65 contains the stride. 


Note that OTS$VPOWDD_R1_V8 raises a D-floating base to a D-floating power, 
which you determine from the DD in the routine name. (For further explanation, 
refer to Section 2.3.3.) The stride (the number of array elements that are skipped) 
must be a multiple of 8 because each D-floating value requires 8 bytes. 


7 ; RO/R1 already contains the power 
MTVLR #60 ; Load VLR 


MOVL #8, R5 + Stride 

VLDQ (R4), R5, VO ; Load VO with the actual arguments 
CALLS  #0,G*OTSSVPOWDD R1 V8 ; CALL OTS$VPOWDD 

VSTQ VO, (R6), R5 ; Store the results 


2.4 Fast-Vector Math Routines 


This section describes the fast-vector math routines that offer significantly 
higher performance at the cost of slightly reduced accuracy when compared with 
corresponding standard vector math routines. Also note that some fast-vector 
math routines have restricted argument domains. 


When you specify the compile command qualifiers /(VECTOR and /MATH_ 
LIBRARY=FAST, VAX FORTRAN-HPO Version 1.2 selects the appropriate fast- 
vector math routine, if one exists. The default is /MATH LIBRARY=ACCURATE. 
You must specify the /G_FLOATING compile qualifier in conjunction with the 
/MATH_LIBRARY=FAST and /VECTOR qualifiers to access the G_floating 
versions from VAX FORTRAN-HPO. See the VAX FORTRAN-HPO V1.2 Release 
Notes for more information. 


You can call these routines from VAX MACRO using the standard calling method. 
The math function names, together with corresponding entry points of the 
fast-vector math routines, are listed in Table 2-5. 
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Table 2—5 Fast-Vector Math Routines 


Function Name 


ATAN 

DATAN 
GATAN 
ATAN2 
DATAN2 
GATAN2 

COS 

DCOS 

GCOS 

EXP 

DEXP 

GEXP 

LOG 

DLOG 

GLOG 

LOG10 
DLOGI1O0 
GLOG10 

SIN 

DSIN 

GSIN 

SQRT 

DSQRT 
GSQRT 

TAN 

DTAN 

GTAN 
POWRR(X**Y) 
POWDD(X**Y) 
POWGG(X**Y) 


Vector Vector 

Input Output Vector Name 
Data Type Callor JSB Registers Registers (Underflows Not Signaled) 
F_floating JSB Vo vo MTH$VYATAN_RO_V3 
D_floating JSB Vo Vo MTH$VYDATAN_RO_V5 
G_floating JSB vo vo MTH$VYGATAN_RO_V5 
F_floating JSB vo, V1 vo MTH$VVYATAN2_RO_V5 
D_floating JSB vo, V1 vo MTH$VVYDATAN2_R0O_V5 
G_floating JSB vo, Vl vo MTH$VVYGATAN2_RO_V5 
F_floating JSB Vo vo 7 MTH$VYCOS_RO_V3 
D_floating JSB VO vo MTH$VYDCOS_R0_V3 
G_floating JSB Vo Vo MTH$VYGCOS_RO_V3 
F floating JSB VO vo MTH$VYEXP_RO_V4 
D_floating JSB Vo vo MTH$VYDEXP_RO_V6 
G_floating JSB VO VO MTH$VYGEXP_RO_V6 
F floating JSB Vo vo MTH$VYALOG_RO_V5 
D_floating JSB VO vo MTH$VYDLOG_RO_V5 
G_floating JSB VO - VO MTH$VYGLOG_RO_V5 
F_floating JSB Vo VO MTH$VYALOG10_RO_V5 
D_floating JSB Vo vo MTH$VYDLOG10_R0O_V5 
G_floating JSB VO vo MTH$VYGLOG10_R0_V5 
F_floating JSB vo VO MTH$VYSIN_RO_V3 
D_floating JSB VO VO MTH$VYDSIN_RO_V3 
G_floating JSB Vo vo MTH$VYGSIN_RO_V3 
F floating JSB Vo vo MTH$VYSQRT_RO_V4 
D_floating JSB VO VO MTH$VYDSQRT_RO_V4 
G_floating JSB VO vo MTH$VYGSQRT_RO_V4 
F floating JSB VO vo MTH$VYTAN_RO_V8 
D_floating JSB VO VO MTH$VYDTAN_RO_V3 
G_floating JSB VO vo MTH$VYGTAN_RO_V3 
F_floating CALL VO, RO vo OTS$VYPOWRR_R1_V4 
D_floating CALL VO, RO vo OTS$VYPOWDD_R1_V8 
G_floating CALL VO, RO Vo OTS$VYPOWGG_R1_V9 


2.4.1 Exception Handling 
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The fast-vector math routines signal all errors except floating underflow. No 
intermediate calculations result in exceptions. To optimize performance, the 
following message signals all errors: 


%SYSTEM-F-VARITH, vector arithmetic fault 


Vector Routines in MTH$ 
2.4 Fast-Vector Math Routines 


2.4.2 Special Restrictions On Input Arguments 


The special restrictions listed in Table 2—6 apply only to fast-vector routines 
SIN, COS, and TAN. The standard vector routines handle the full range of VAX 
floating point numbers. 


Table 2—6 Input Argument Restrictions 


Function Name Input Argument Domain (in Radians) 
SIN ~( -6746518783.0, 6746518783.0) 
COS ~( -6746518783.0, 6746518783.0) 
TAN ~( -8373259391.5, 3373259391.5 ) 


If the application program uses arguments outside of the listed domain, the 
routine returns the following error message: 


%SYSTEM-F-VARITH, vector arithmetic fault 


If the application requires argument values beyond the listed limits, use the 
corresponding standard vector math routine. 


2.4.3 Accuracy 


The fast-vector math routines do not guarantee the same results as those obtained 
with the corresponding standard vector math routines. Calls to the fast-vector 
routines generally yield results that are different from the scalar and original 
vector MTH$ library routines. The typical maximum error is a 2-LSB (Least 
Significant Bit) error for the F_floating routines and a 4-LSB error for the D_ 
floating and G_floating routines. This generally corresponds to a difference in 
the 6th significant decimal digit for the F_floating routines, the 15th digit for 
D_floating, and the 14th digit for G_floating. 


2.4.4 Performance 


The fast-vector math routines generally provide performance improvements over 
the standard vector routines ranging from 15 to 300 percent, depending on the 
routines called and input arguments to the routines. The overall performance 
improvement using fast-vector math routines in a typical user application will 
increase, but not at the same level as the routines themselves. You should do 
performance and correctness testing of your application using both the fast-vector 
and the standard vector math routines before deciding which to use for your 
application. 
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Scalar MTHS Reference Section 


The Scalar MTH$ Reference Section provides detailed descriptions of the scalar 
routines provided by the OpenVMS RTL Mathematics (MTH$) Facility. 


MTH$xACOS 


MTH$xACOS—Arc Cosine of Angle Expressed in Radians 


Given the cosine of an angle, the Arc Cosine of Angle Expressed in Radians 
routine returns that angle (in radians). 


Format 
MTH$ACOS cosine 
MTH$DACOS cosine 
MTH$GACOS cosine 
Each of the above three formats accepts one of the floating-point types as input. 
JSB Entries 
MTH$ACOS_R4 
MTH$DACOS_R7 
MTH$GACOS_R7 
Each of the above three JSB entries accepts one of the floating-point types as 
input. 
Returns 
OpenVMS usage _floating_point 
type F_ floating, D_floating, G_floating 
access write only 
mechanism by value 
Angle in radians. The angle returned will have a value in the range 
O<angle <a 
MTH$ACOS returns an F-floating number. MTH$DACOS returns a D-floating 
number. MTH$GACOS returns a G-floating number. 
Arguments 
cosine 
OpenVMS usage _ floating_point 
type F_floating, D_floating, G_floating 
access read only 
mechanism by reference 


The cosine of the angle whose value (in radians) is to be returned. The cosine 
argument is the address of a floating-point number that is this cosine. The 
absolute value of cosine must be less than or equal to 1. For MTH$ACOS, 
cosine specifies an F-floating number. For MTH$DACOS, cosine specifies a 
D-floating number. For MTH$GACOS, cosine specifies a G-floating number. 


Ra"rTT Ge OA 


MTH$xACOS 


Description 


The angle in radians whose cosine is X is computed as: 


Value of Cosine Value Returned 


-1<X <0 
1 < |X| 


n [2 
0 


T 


zATAN(zSQRT(1— X*)/X), where zATAN and zSQRT are the 
Math Library arc tangent and square root routines, respectively, 
of the appropriate data type 

zATAN(zSQRT(1— X?)/X)4+1x 

The error MTH$_INVARGMAT is signaled 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HACOS. 


Condition Values Signaled 


Examples 


AATLI A 


SS$_ROPRAND Reserved operand. The MTH$xACOS routine 


encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$_INVARGMAT Invalid argument. The absolute value of cosine 


1. 100 


300 
400 


500 
32767 


is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 


change CHF$L_MCH_SAVRO/R1. 


I+ 
! This BASIC program demonstrates the use of 


! MTHSACOS. 
1_ 


EXTERNAL REAL FUNCTION MTHSACOS 
DECLARE REAL COS VALUE, ANGLE 
INPUT "Cosine value between -1 and +1 "; COS VALUE 
IF (COS VALUE < -1) OR (COS VALUE > 1) ~ 

THEN PRINT "Invalid cosine value" 

GOTO 300 

ANGLE = MTHSACOS( COS VALUE ) 
PRINT "The angle with that cosine is "; ANGLE; "radians" 
END 


MTH$xACOS 


This BASIC program prompts for a cosine value and determines the angle 
that has that cosine. The output generated by this program is as follows: 


$ RUN ACOS 
Cosine value between -1 and +1 ? .5 
The angle with that cosine is 1.0472 radians 


PROGRAM GETANGLE(INPUT,OUTPUT) ; 


{+} 
{ This PASCAL program uses MTHSACOS to determine 
{ the angle which has the cosine given as input. 


t=} 

VAR 
COS : REAL; 

FUNCTION MTHSACOS(COS : REAL) : REAL; 
EXTERN; 

BEGIN 
WRITE('’Cosine value between -1 and +1: '); 
READ (COS); 
WRITELN(‘The angle with that cosine is ', MTHSACOS(COS), 
‘ radians’); 

END. 


This PASCAL program prompts for a cosine value and determines the angle 
that has that cosine. The output generated by this program is as follows: 


S$ RUN ACOS 
Cosine value between ~1 and +1: .5 
The angle with that cosine is 1.04720E+00 radians 


MTH—A 


MTH$xACOSD 


MTH$xACOSD—Arc Cosine of Angle Expressed in Degrees 


Format 


JSB Entries 


Returns 


Arguments 
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Given the cosine of an angle, the Arc Cosine of Angle Expressed in Degrees 
routine returns that angle (in degrees). 


MTH$ACOSD cosine 
MTH$DACOSD cosine 
MTH$GACOSD cosine 


Each of the above formats accepts one of the floating-point types as input. 


MTH$ACOSD_R4 

MTH$DACOSD_R7 

MTH$GACOSD_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F_ floating, D_floating, G_floating 
access write only 
mechanism by value 


Angle in degrees. The angle returned will have a value in the range 


0 < angle < 180 


MTH$ACOSD returns an F-floating number. MTH$DACOSD returns a D-floating 
number. MTH$GACOSD returns a G-floating number. 


cosine 

OpenVMS usage _ floating_point 

type F_floating, G_floating, D_floating 
access read only 

mechanism by reference 


Cosine of the angle whose value (in degrees) is to be returned. The cosine 
argument is the address of a floating-point number that is this cosine. The 
absolute value of cosine must be less than or equal to 1. For MTH$ACOSD, 
cosine specifies an F-floating number. For MTH$DACOSD, cosine specifies a 
D-floating number. For MTH$GACOSD, cosine specifies a G-floating number. 


Description 


MTH$xACOSD 


The angle in degrees whose cosine is X is computed as: 


Value of Cosine Angle Returned 


0 90 
1 0 

—1 180 . 

0<X<1 zATAN D(zSQRT(1 — X7)/X), where zATAND and zSQRT 


are the Math Library arc tangent and square root routines, 
respectively, of the appropriate data type 


-1<X<0 zATAN D(zSQRT(1— X*)/X) + 180 
1 < |X| The error MTH$_INVARGMAT is signaled 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HACOSD. 


Condition Values Signaled 


Example 


SS$_ROPRAND Reserved operand. The MTH$xACOSD routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$ INVARGMAT Invalid argument. The absolute value of cosine 
is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF$L_MCH_SAVRO/R1. 


PROGRAM ACOSD(INPUT,OUTPUT) ; 


{+} 

{ This PASCAL program demonstrates the use of 
{ MTHSACOSD. 

Lee 

FUNCTION MTHSACOSD(COS : REAL): REAL; EXTERN; 


VAR 
COSINE : REAL; 
RET STATUS : REAL; 


BEGIN 

COSINE := 0.5; 

RET STATUS := MTHSACOSD(COSINE); 

WRITELN(‘'The angle, in degrees, is: ', RET STATUS); 
END. 


MTH-7 


MTH$xACOSD 


The output generated by this PASCAL example program is as follows: 


The angle, expressed in degrees, is: 6.00000E+01 


MTH-8 


MTHSxASIN 


MTH$xASIN—Arc Sine in Radians 


Format 


JSB Entries 


Returns 


Arguments 


Given the sine of an angle, the Arc Sine in Radians routine returns that angle (in 
radians). 


MTHSASIN - sine 
MTHS$DASIN sine 
MTH$GASIN _ sine 


Each of the above formats accepts one of the floating-point types as input. 


MTH$ASIN_R4 

MTH$DASIN_R7 

MTH$GASIN_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


Angle in radians. The angle returned will have a value in the range 


—1/2< angle < 1/2 


MTH$ASIN returns an F-floating number. MTH$DASIN returns a D-floating 
number. MTH$GASIN returns a G-floating number. 


sine 

OpenVMS usage _ floating_point 

type F floating, D_floating, G_floating 
access read only 

mechanism | by reference 


The sine of the angle whose value (in radians) is to be returned. The sine 
argument is the address of a floating-point number that is this sine. The absolute 
value of sine must be less than or equal to 1. For MTH$ASIN, sine specifies an 
F-floating number. For MTH$DASIN, sine specifies a D-floating number. For 
MTH$GASIN, sine specifies a G-floating number. 


MTH-9 


MTHS$xASIN 


Description 


The angle in radians whose sine is X is computed as: 


Value of Sine 
0 

1 

—] 
0<|X|<1 


1< |X| 


Angle Returned 


0 

a /2 

—n/2 

zATAN(X/zSQRT(1— X*)), where zATAN and zSQRT are 


the Math Library arc tangent and square root routines, 
respectively, of the appropriate data type 


The error MTH$ INVARGMAT is signaled 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HASIN. 


Condition Values Signaled 


MTH-10 


SS$_ROPRAND 


MTH$_INVARGMAT 


Reserved operand. The MTH$xASIN routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. The absolute value of sine 

is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF$L_MCH_SAVRO/R1. 


MTH$xASIND 


MTH$xASIND—Arc Sine in Degrees 


Format 


JSB Entries 


Returns 


Arguments 


Given the sine of an angle, the Arc Sine in Degrees routine returns that angle (in 
degrees). 


MTH$ASIND sine 
MTH$DASIND sine 
MTHS$GASIND sine 


Each of the above formats accepts one of the floating-point types as input. 


MTH$ASIND_R4 

MTH$DASIND_R7 

MTH$GASIND_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


Angle in degrees. The angle returned will have a value in the range 


—90 < angle < 90 


MTH$ASIND returns an F-floating number. MTH$DASIND returns a D-floating 
number. MTH$GASIND returns a G-floating number. 


sine 

OpenVMS usage _ floating_point 

type F_floating, D_floating, G_floating 
access read only 

mechanism by reference 


Sine of the angle whose value (in degrees) is to be returned. The sine argument 
is the address of a floating-point number that is this sine. The absolute value 
of sine must be less than or equal to 1. For MTH$ASIND, sine specifies an 
F-floating number. For MTH$DASIND, sine specifies a D-floating number. For 
MTH$GASIND, sine specifies a G-floating number. 


MTH-11 


MTH$xASIND 


Description 


The angle in degrees whose sine is X is computed as: 


Value of Sine 
0 

1 

—] 

0< |X|<1 


1 < |X| 


Value Returned 


0 
90 
—90 


zATAN D(X/zSQRT(1 — X*)), where zATAND and zSQRT 
are the Math Library arc tangent and square root routines, 
respectively, of the appropriate data type 


The error MTH$_INVARGMAT is signaled 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HASIND. 


Condition Values Signaled 


MTH-12 


SS$_ROPRAND 


MTH$_INVARGMAT 


Reserved operand. The MTH$xASIND routine 
encountered a floating point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. The absolute value of sine 

is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF$L_MCH_SAVRO/R1. 


MTHSxATAN 


MTH$xATAN—Arc Tangent in Radians 


Format 


JSB Entries 


Returns 


Arguments 


Given the tangent of an angle, the Arc Tangent in Radians routine returns that 
angle (in radians). 


MTH$ATAN _ tangent 
MTHS$DATAN _ tangent 
MTHS$GATAN _ tangent 


Each of the above formats accepts one of the floating-point types as input. 


MTH$SATAN_R4 

MTH$DATAN_R7 

MTH$GATAN_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type EF’ floating, D_floating, G_floating 
access write only 
mechanism by value 


Angle in radians. The angle returned will have a value in the range 


—1/2< angle < n/2 


MTHS$ATAN returns an F-floating number. MTH$DATAN returns a D-floating 
number. MTH$GATAN returns a G-floating number. 


tangent 

OpenVMS usage  floating_point 

type F’ floating, D_floating, G_floating 
access read only 

mechanism by reference 


The tangent of the angle whose value (in radians) is to be returned. The tangent 
argument is the address of a floating-point number that is this tangent. For 
MTH$ATAN, tangent specifies an F-floating number. For MTH$DATAN, 
tangent specifies a D-floating number. For MTH$GATAN, tangent specifies a 
G-floating number. 
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MTH$xATAN 


Description 


In radians, the computation of the arc tangent function is based on the following 
identities: 
arctan(X) = X — X3/34 X°/5— X"/74... 
arctan(X) = X + X * Q(X%), 
where Q(Y) = -Y/3+ Y2/5—Y3/7+... 
arctan(X) = X « P(X), 
where P(Y) =1-—Y/3+Y2/5—Y2/7+... 
arctan(X) = 2/2 — arctan(1/X) 
arctan(X) = arctan(A) + arctan((X — A)/(1+ A X)) 
for any real A 


The angle in radians whose tangent is X is computed as: 


Value of X Angle Returned 

0<X<3/32 X + X* Q(X?) 

3/32 < X<11 ATAN(A) + V « (P(V7)), where A and ATAN(A) are 
chosen by table lookup and V = (X — A)/(1+ A* X) 

11< X 1/2—W +(P(W7)) where W = 1/X 

X <0 ~zATAN(|X)) 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HATAN. 


Condition Value Signaled 


MTH-—14 


SS$ ROPRAND Reserved operand. The MTH$xATAN routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$xATAND 


MTH$xATAND—Arc Tangent in Degrees 


Format 


JSB Entries 


Returns 


Arguments 


Given the tangent of an angle, the Arc Tangent in Degrees routine returns that 
angle (in degrees). | 


MTH$ATAND — tangent 
MTH$DATAND _ tangent 
MTH$GATAND _ tangent 


Each of the above formats accepts one of the floating-point types as input. 


MTH$ATAND_R4 

MTH$DATAND_R7 

MTH$GATAND_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


Angle in degrees. The angle returned will have a value in the range 


—90 < angle < 90 


MTH$ATAND returns an F-floating number. MTH$DATAND returns a D-floating 
number. MTH$GATAND returns a G-floating number. 


tangent 

OpenVMS usage _ floating_point 

type F floating, D_floating, G_floating 
access read only 

mechanism by reference 


The tangent of the angle whose value (in degrees) is to be returned. The tangent 
argument is the address of a floating-point number that is this tangent. For 
MTH$ATAND, tangent specifies an F-floating number. For MTH$DATAND, 
tangent specifies a D-floating number. For MTH$GATAND, tangent specifies a 
G-floating number. 


NMATH—15 


MTH$xATAND 


Description 


The computation of the are tangent function is based on the following identities: 
arctan(X) = (180/z) « (X — X? /3 + X°/5 — X"/74 sta) 
arctan(X) = 64* X + X+ Q(X), 
where Q(Y) = 180/m « |(1— 64 + 7/180)] — Y/3+ Y2/5-— Y?/7+ ¥*/9 
arctan(X) = X # P(X?), 
where P(Y) = 180/a + {1—- Y/3+ Y2/5 — Y3/74+ Y*4/9.., 
arctan(X) = 90 — arctan(1/X) 
arctan(X) = arctan(A) + arctan((X — A)/(1+ A* X)) 


The angle in degrees whose tangent is X is computed as: 


Tangent Angle Returned 

X<3/32 64% X+ X+ Q(X?) 

3/32 < X<11 ATAND(A) + V * P(V2), where A and ATAND(A) are 
chosen by table lookup and V = (X — A)/(1+ A * X) 

11<X 90 — W « (P(W7)), where W = 1/X 

xX <0 -ZATAND( | X I ) 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HATAND. 


Condition Value Signaled 


MTH—16 


SS$_ ROPRAND Reserved operand. The MTH$xATAND routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$xATAN2 


MTH$xATAN2—Arc Tangent in Radians with Two Arguments 


Format 


Returns 


Arguments 


Given sine and cosine, the Arc Tangent in Radians with Two Arguments routine 
returns the angle (in radians) whose tangent is given by the quotient of sine and 
cosine (sine/cosine). 


MTH$ATANZ sine ,cosine 
MTH$DATANZ2 sine ,cosine 
MTH$GATANZ sine ,cosine 


Each of the above formats accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


Angle in radians. MTH$ATAN2 returns an F-floating number. MTH$DATAN2 
returns a D-floating number. MTH$GATAN2 returns a G-floating number. 


sine 

OpenVMS usage floating_point 

type F floating, D_floating, G_floating 
access read only 

mechanism by reference 


Dividend. The sine argument is the address of a floating-point number that 

is this dividend. For MTH$ATAN2Q, sine specifies an F-floating number. For 

MTH$DATAN2, sine specifies a D-floating number. For MTH$GATAN2, sine 
specifies a G-floating number. 


cosine 

OpenVMS usage floating_point 

type ¥'_ floating, D_floating, G_floating 
access read only 

mechanism by reference 


Divisor. The cosine argument is the address of a floating-point number that 
is this divisor. For MTH$ATAN2, cosine specifies an F-floating number. For 
MTH$DATAN2, cosine specifies a D-floating number. For MTH$GATAN2, 
cosine specifies a G-floating number. 


NATHUOU17 


MTH$xATAN2 


Description 


The angle in radians whose tangent is Y/X is computed as follows, where f is 
defined in the description of MTH$zCOSH. 


Value of Input Arguments 
X=OorY/X > 2h) 
X>Oand Y/X< 2D 
X <Oand Y/XK< 260 


Angle Returned 

m/2* (signY) 
zATAN(Y/X) 

am * (stegnY) + zATAN(Y/X) 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HATAN2. 


Condition Values Signaled 


MTH-18 


SS$_ROPRAND 


MTH$_INVARGMAT 


Reserved operand. The MTH$xATAN2 routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. Both cosine and sine are 
zero. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_MCH_ SAVRO/R1. The result 

is the floating-point reserved operand unless 
you have written a condition handler to change 


CHF$L_MCH_SAVRO/R1. 


MTHSxATAND2 


MTH$xATAND2—Arc Tangent in Degrees with Two Arguments 


Format 


Returns 


Arguments 


Given sine and cosine, the Arc Tangent in Degrees with Two Arguments routine 
returns the angle (in degrees) whose tangent is given by the quotient of sine and 
cosine (sine/cosine). 


MTH$ATANDZ2 sine ,cosine 
MTH$DATANDZ2 sine ,cosine 
MTH$GATANDZ2 sine ,cosine 


Each of the above formats accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


Angle (in degrees). MTH$ATAND2 returns an F-floating number. 
MTH$DATAND2 returns a D-floating number. MTH$GATAND2 returns a 
G-floating number. 


sine 

OpenVMS usage  floating_point 

type F’ floating, D_floating, G_floating 
access read only 

mechanism by reference 


Dividend. The sine argument is the address of a floating-point number that 

is this dividend. For MTH$ATAND2, sine specifies an F-floating number. For 
MTH$DATAND2, sine specifies a D-floating number. For MTH$GATAND2, sine 
specifies a G-floating number. 


cosine 

OpenVMS usage _ floating_point 

type F_floating, D_floating, G_floating 
access read only 

mechanism by reference 


Divisor. The cosine argument is the address of a floating-point number that 
is this divisor. For MTH$ATAND2, cosine specifies an F-floating number. For 
MTH$DATAND2, cosine specifies a D-floating number. For MTH$GATAND2, 
cosine specifies a G-floating number. 


MTH$xATAND2 


Description 


The angle in degrees whose tangent is Y/X is computed below and where f is 
defined in the description of MTH$zCOSH. 


Value of Input Arguments 
X=OorY/X> o(f+l) 

X>OandY/X < 2htv 
X <Oand Y/X < 204+) 


Angle Returned 

90 « (stegnY) 

zATAND(Y/X) 

180 * (stgnY) + zATAND(Y/X) 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HATAND2. 


Condition Values Signaled 


AATLI ON 


SS$_ROPRAND 


MTH$_INVARGMAT 


Reserved operand. The MTH$xATAND2 routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. Both cosine and sine are 
zero. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_MCH_SAVRO/R1. The result 

is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


MTH$xATANH 


MTH$xATANH—Hyperbolic Arc Tangent 


Format 


Returns 


Arguments 


Description 


Given the hyperbolic tangent of an angle, the Hyperbolic Arc Tangent routine 
returns the hyperbolic arc tangent of that angle. 


MTH$ATANH = hyperbolic-tangent 
MTH$DATANH _ hyperbolic-tangent 
MTH$GATANH _hyperbolic-tangent 


Each of the above formats accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F’_fioating, D_floating, G._ floating 
access write only 
mechanism by value 


The hyperbolic arc tangent of hyperbolic-tangent. MTH$ATANH returns an 
F-floating number. MTH$DATANH returns a D-floating number. MTH$GATANH 
returns a G-floating number. 


hyperbolic-tangent 
OpenVMS usage  floating_point 


type F_floating, D_floating, G_floating 
access read only | 
mechanism by reference 


Hyperbolic tangent of an angle. The hyperbolic-tangent argument is the 
address of a floating-point number that is this hyperbolic tangent. For 
MTH$ATANH, hyperbolic-tangent specifies an F-floating number. For 
MTH$DATANH, hyperbolic-tangent specifies a D-floating number. For 
MTH$GATANH, hyperbolic-tangent specifies a G-floating number. 


The hyperbolic arc tangent function is computed as follows: 


Value of x Value Returned 
|X| <j zATAN A(X) = z2LOG((1+ X)/(1—- X))/2 
|\X|>1 An invalid argument is signaled 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HATANH. 


RATII “Aad 


MTH$xATANH 


Condition Values Signaled 


AATLU 99 


SS$_ROPRAND 


MTH$_INVARGMAT 


Reserved operand. The MTH$xATANH routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument: |X|>1. LIB$SIGNAL copies 
the floating-point reserved operand to the 
mechanism argument vector CHF$L_MCH_ 
SAVRO/R1. The result is the floating-point 
reserved operand unless you have written a 
condition handler to change CHF $L_MCH_ 
SAVRO/R1. 


MTHS$CxABS 


MTH$CxABS—Complex Absolute Value 


Format 


Returns 


Arguments 


Description 


The Complex Absolute Value routine returns the absolute value of a complex 
number (r,1). 


MTH$CABS _ complex-number 
MTH$CDABS _complex-number 
MTH$CGABS_ complex-number 


Each of the above three formats accepts one of the three floating-point complex 
types as input. 


OpenVMS usage _ floating_point 


type F_ floating, D_floating, G_floating 
access write only 
mechanism by value 


The absolute value of a complex number. MTH$CABS returns an F-floating 
number. MTH$CDABS returns a D-floating number. MTH$CGABS returns a 
G-floating number. 


complex-number 
OpenVMS usage complex_number 


type IF’ floating complex, D_floating complex, G_floating complex 
access read only 
mechanism by reference 


A complex number (1,1), where r and i are both floating-point complex values. 
The complex-number argument is the address of this complex number. For 
MTH$CABS, complex-number specifies an F-floating complex number. For 
MTH$CDABS, complex-number specifies a D-floating complex number. For 
MTH$CGABS, complex-number specifies a G-floating complex number. 


The complex absolute value is computed as follows, where MAX is the larger of 
[rl and 1il,and MIN is the smaller of |r| and lil. 


result = MAX « SQRT((MIN/MAX)? +1) 


MTH$CxABS 


Condition Values Signaled 


Examples 


SS$_ROPRAND Reserved operand. The MTH$CxABS routine 


encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$ FLOOVEMAT Floating-point overflow in Math Library when 


a en ee 


Ct 


C- 


C+ 


C- 


both r and i are large. 


This FORTRAN example forms the absolute value of an 
F-~floating complex number using MTHSCABS and the 
FORTRAN random number generator RAN. 


Declare Z as a complex value and MTHSCABS as a REAL*4 value. 
MTHSCABS will return the absolute value of Z: 4% NEW = MTHSCABS(Z). 


COMPLEX Z 

COMPLEX CMPLX 

REAL*4 Z NEW,MTHSCABS 
INTEGER M 

M = 1234567 


Generate a random complex number with the FORTRAN generic CMPLX. 
Z = CMPLX(RAN(M),RAN(M)) 


Z is a complex number (r,i1) with real part "r" and 
imaginary part "i". 


TYPE *, ' The complex number z is’,z 
TYPE *, ' It has real part’,REAL(Z),'’and imaginary part’ ,AIMAG(Z) 
TYPE *, : 


~ 


Compute the complex absolute value of Z. 


Z NEW = MTHSCABS(Z) 
TYPE *, ' The complex absolute value of',z,' is',Z NEW 
END 


This example uses an F-floating complex number for complex-number. The 
output of this FORTRAN example is as follows: 


The complex number z is (0.8535407,0.2043402) 
It has real part 0.8535407 and imaginary part 0.2043402 


The complex absolute value of (0.8535407,0.2043402) is 0.8776597 


+ 


MlMAAARQAAQANAANM 


C+ 


C= 


MTH$CxABS 


This FORTRAN example forms the absolute 
value of a G-floating complex number using 
MTHSCGABS and the FORTRAN random number 
generator RAN. 


Declare Z as a complex value and MTHSCGABS as a 
REAL*8 value. MTHSCGABS will return the absolute 
value of Z: Z NEW = MTHSCGABS(Z). 


COMPLEX*16 Z 
REAL*8 Z NEW,MTHSCGABS 


Generate a random complex number with the FORTRAN 
generic CMPLX. 


Z = (12.34567890123,45.536376385345) 
TYPE *, ' The complex number Zz is’,z 
TYPE *, ' ! 


Compute the complex absolute value of 2Z. 


Z NEW = MTHSCGABS(Z) 
TYPE *, ' The complex absolute value of’,z,' is’,Z NEW 
END 


This FORTRAN example uses a G-floating complex number for complex- 
number. Because this example uses a G-floating number, it must be 
compiled as follows: 


S FORTRAN/G MTHEX.FOR 


Notice the difference in the precision of the output generated: 


The complex number z is (12.3456789012300,45.5363763853450) 
The complex absolute value of (12.3456789012300,45.5363763853450) is 
47.1802645376230 


MTH-25 


MTH$CCOS 


MTH$CCOS—Cosine of a Complex Number (F-Floating Value) 


The Cosine of a Complex Number (F-Floating Value) routine returns the cosine of 
a complex number as an F-floating value. 


Format 
MTH$CCOS_ complex-number 


Returns 


OpenVMS usage complex_number 
type F_floating complex 
access write only 
mechanism by value 


The complex cosine of the complex input number. MTH$CCOS returns an 
F-floating complex number. 


Arguments 


complex-number 

OpenVMS usage complex_number 
type F floating complex 
access read only 
mechanism by reference 


A complex number (r,i) where r and i are floating-point numbers. The complex- 
number argument is the address of this complex number. For MTH$CCOS, 
complex-number specifies an I'-floating complex number. 


Description 


The complex cosine is calculated as follows: 
result = (COS(r) * COS H(z), -—SIN(r) + SIN H(:)) 


The routine descriptions for the D- and G-floating point versions of this routine 
are listed alphabetically under MTH$CxCOS. 


Condition Values Signaled 


SS$_ROPRAND Reserved operand. The MTH$CCOS routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
‘use by Digital. 


MTH$_FLOOVEMAT Floating-point overflow in Math Library: the 
absolute value of 1 is greater than about 88.029 
for F-floating values. 


MTH-26 


Example 


MTH$CCOS 


+ 


This FORTRAN example forms the complex 
cosine of an F-floating complex number using 
MTHSCCOS and the FORTRAN random number 
generator RAN. 


Declare Z and MTHSCCOS as complex values. 
MTHSCCOS will return the cosine value of 
Zs Z NEW = MTHSCCOS(Z) 


MAAARAARQAARAAANQ 


COMPLEX Z,Z NEW,MTHSCCOS 
COMPLEX CMPLX 

INTEGER M 

M = 1234567 


C Generate a random complex number with the 
C FORTRAN generic CMPLX. 


C- 
Z = CMPLX(RAN(M) ,RAN(M) ) 
Ct 
C Z is a complex number (r,i) with real part "r" and 
C imaginary part "i". 
C= 
TYPE *, ‘' The complex number z is’,z 
TYPE *, ' It has real part’,REAL(Z),’and imaginary part’ ,AIMAG(Z) 
TYPE *, ' ! 
C+ 
C Compute the complex cosine value of 2. 
C- 


2 NEW = MTHS$CCOS(Z) 
TYPE *, ’ The complex cosine value of',z,' is',Z NEW 
END 


This FORTRAN example demonstrates the use of MTH$CCOS, using the 
MTH$CCOS entry point. The output of this program is as follows: 


The complex number z is (0.8535407,0.2043402) 
It has real part 0.8535407 and imaginary part 0.2043402 
The complex cosine value of (0.8535407,0.2043402) is (0.6710899,-0.1550672) 


MTH—27 


MTH$CxCOS 


MTH$CxCOS—Cosine of a Complex Number 


The Cosine of a Complex Number routine returns the cosine of a complex number. 


Format 
MTH$CDCOS_ complex-cosine ,complex-number 
MTH$CGCOS_ complex-cosine ,complex-number 


Each of the above formats accepts one of the floating-point complex types as 
input. 


Returns 


None. 


Arguments 


complex-cosine 

OpenVMS usage complex_number 

type D_floating complex, G_floating complex 
access write only 

mechanism by reference 


Complex cosine of the complex-number. The complex cosine routines that have 
D-floating and G-floating complex input values write the address of the complex 
cosine into the complex-cosine argument. For MTH$CDCOS, the complex- 
cosine argument specifies a D-floating complex number. For MTH$CGCOS, the 
complex-number argument specifies a G-floating complex number. 


complex-number 

OpenVMS usage complex_number 

type D_floating complex, G_floating complex 
access read only 

mechanism by reference 


A complex number (1,1) where r and i are floating-point numbers. The complex- 
number argument is the address of this complex number. For MTH$CDCOS, 
complex-number specifies a D-floating complex number. For MTH$CGCOS, 
complex-number specifies a G-floating complex number. 


Description 


The complex cosine is calculated as follows: 


result = (COS(r) * COS H (2), —SIN(r) « SIN H(t)) 


MTH-28 


MTH$CxCOS 


Condition Values Signaled 


Example 


SS$_ ROPRAND Reserved operand. The MTH$CxCOS routine 


encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$_FLOOVEMAT Floating-point overflow in Math Library: the 


+ 


MAAMTAARANRAAN 


Cr 


C- 


absolute value of 1 is greater than about 88.029 
for F-floating and D-floating values, or greater 
than 709.089 for G-floating values. 


This FORTRAN example forms the complex 
cosine of a D-floating complex number using 
MTHSCDCOS and the FORTRAN random number 
generator RAN. 


Declare Z and MTHSCDCOS as complex values. 
MTHSCDCOS will return the cosine value of 
Zs Z NEW = MTHSCDCOS(Z) 


COMPLEX*16 Z,Z NEW,MTHSCDCOS 
COMPLEX*16 DCMPLX 

INTEGER M 

M = 1234567 


Generate a random complex number with the 
FORTRAN generic DCMPLX. 


2 = DCMPLX(RAN(M) ,RAN(M)) 


Z is a complex number (r,i) with real part "r" and 
imaginary part "i". 


TYPE *, ‘' The complex number z is’,z 
TYPE? 


Compute the complex cosine value of Z. 


2 NEW = MTHSCDCOS(Z) 
TYPE *, ' The complex cosine value of',z,’ is’,2Z NEW 
END 


This FORTRAN example program demonstrates the use of MTH$CxCOS, using 
the MTH$CDCOS entry point. Notice the high precision of the output generated: 


The complex number z is (0.8535407185554504,0.2043401598930359) 
The complex cosine value of (0.8535407185554504,0.2043401598930359) is 


(0.6710899028500762,-0.1550672019621661) 


MTH-29 


MTH$CEXP 


MTHSCEXP—Complex Exponential (F-Floating Value) 


Format 


Returns 


Arguments 


Description 


The Complex Exponential (F-Floating Value) routine returns the complex 
exponential of a complex number as an F-floating value. 


MTH$CEXP complex-number 


OpenVMS usage complex_number 


type F_floating complex 
access write only 
mechanism by value 


Complex exponential of the complex input number. MTH$CEXP returns an 
F-floating complex number. 


complex-number 
OpenVMS usage complex_number 


type F_floating complex 
access read only 
mechanism by reference 


Complex number whose complex exponential is to be returned. This complex 
number has the form (1,1), where r is the real part and 1 is the imaginary part. 
The complex-number argument is the address of this complex number. For 
MTH$CEXP, complex-number specifies an F-floating number. 


The complex exponential is computed as follows: 


complex — exponent = (EX P(r) * COS(z), EX P(r) « SIN(2)) 


The routine descriptions for the D- and G-floating point versions of this routine 
are listed alphabetically under MTH$CxEXP. 


Condition Values Signaled 


MTH-30 


SS$_ ROPRAND Reserved operand. The MTH$CEXP routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$ FLOOVEMAT Floating-point overflow in Math Library: the 
absolute value of r is greater than about 88.029 
for F-floating values. 


Example 


Co ae eee ee 


Ct 


C- 


MTHS$CEXP 


This FORTRAN example forms the complex exponential 
of an F-floating complex number using MTHSCEXP 
and the FORTRAN random number generator RAN. 


Declare Z and MTHSCEXP as complex values. MTHSCEXP 
will return the exponential value of Z: Z NEW = MTHSCEXP(Z) 


COMPLEX 2,2 NEW, MTHSCEXP 
COMPLEX CMPLX 

INTEGER M 

M = 1234567 


Generate a random complex number with the 
FORTRAN generic CMPLX. 


Z = CMPLX(RAN(M),RAN(M)) 


Z is a complex number (r,i) with real part "r" 
and imaginary part "i". 


TYPE *, ' The complex number z is’,z 
TYPE *, ' It has real part’,REAL(Z),’and imaginary part’ ,AIMAG(Z) 
TYPE *, ' ! 


Compute the complex exponential value of 2Z. 


Z NEW = MTHSCEXP(Z) 
TYPE *, ' The complex exponential value of',z,' is’,2Z NEW 
END 


This FORTRAN program demonstrates the use of MTH$CEXP as a function call. . 
The output generated by this example is as follows: 


The complex number z is (0.8535407,0.2043402) 
It has real part 0.8535407 and imaginary part 0.2043402 
The complex exponential value of (0.8535407,0.2043402) is 


(2.299097,0.4764476) 


MTH-31 


MTH$CxEXP 


MTH$CxEXP—Complex Exponential 


The Complex Exponential routine returns the complex exponential of a complex 
number. 


Format 
MTH$CDEXP_ complex-exponent ,complex-number 
MTH$CGEXP_ complex-exponent ,complex-number 


Each of the above formats accepts one of the floating-point complex types as 
input. 


Returns 


None. 


Arguments 


complex-exponent 

OpenVMS usage complex_number 

type D_floating complex, G_floating complex 
access write only 

mechanism by reference 


Complex exponential of complex-number. The complex exponential routines 
that have D-floating complex and G-floating complex input values write the 
complex-exponent into this argument. For MTH$CDEXP, complex-exponent 
argument specifies a D-floating complex number. For MTH$CGEXP, complex- 
exponent specifies a G-floating complex number. 


complex-number 

OpenVMS usage complex_number 

type D_floating complex, G_floating complex 
access read only 

mechanism by reference 


Complex number whose complex exponential is to be returned. This complex 
number has the form (r,i), where r is the real part and z is the imaginary 
part. The complex-number argument is the address of this complex number. 
For MTH$CDEXP, complex-number specifies a D-floating number. For 
MTH$CGEXP, complex-number specifies a G-floating number. 

Description 


The complex exponential is computed as follows: 


complex — exponent = (EX P(r) * COS(t), EX P(r) * SIN(z2)) 


MTH-32 


MTH$CxEXP 


Condition Values Signaled 


Example 


SS$_ROPRAND Reserved operand. The MTH$CxEXP routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 

MTH$_ FLOOVEMAT Floating-point overflow in Math Library: the 
absolute value of r is greater than about 88.029 
for D-floating values, or greater than about 
709.089 for G-floating values. 


C+ 
C This FORTRAN example forms the complex exponential 
C of a G-floating complex number using MTHS$CGEXP 
C and the FORTRAN random number generator RAN. 
C 
C Declare Z and MTHSCGEXP as complex values. 
C MTHSCGEXP will return the exponential value 
C of Z: CALL MTHS$CGEXP(Z NEW, Z) 
C- 
COMPLEX*16 Z,Z NEW 
COMPLEX*16 MTHSGCMPLX 
REAL*8 R,I 
INTEGER M 
M = 1234567 
Ct 


C Generate a random complex number with the FORTRA 
C- generic CMPLX. . 


C- 
R = RAN(M) 
I = RAN(M) 
Z = MTHSGCMPLX(R,1I) 
TYPE *, ' The complex number z is’,z 
TYPE *,; *° ? 
C+ 
C Compute the complex exponential value of 2. 
C- 


CALL MTHSCGEXP(Z NEW,Z) 
TYPE *, ' The complex exponential value of',z,' is',Z NEW 
END 


This FORTRAN example demonstrates how to access MTH$CGEXP as a 
procedure call. Because G-floating numbers are used, this program must be 
compiled using the command “FORTRAN/G filename”. 


Notice the high precision of the output generated: 


The complex number z is (0.853540718555450,0.204340159893036) 
The complex exponential value of (0.853540718555450,0.204340159893036) is 
(2.29909677719458,0.476447678044977) 


MTH-33 


MTH$CLOG 


MTH$CLOG—Complex Natural Logarithm (F-Floating Value) 


The Complex Natural Logarithm (F-Floating Value) routine returns the complex 
natural logarithm of a complex number as an F-floating value. 


Format 
MTH$CLOG _ complex-number 
Returns | 
OpenVMS usage complex_number 
type | F floating complex 
access write only 
mechanism by value 
The complex natural logarithm of a complex number. MTH$CLOG returns an 
F-floating complex number. 
Arguments 


complex-number 
OpenVMS usage complex_number 


type F_ floating complex 
access read only 
mechanism by reference 


Complex number whose complex natural logarithm is to be returned. This 
complex number has the form (r,i), where r is the real part and i is the imaginary 
part. The complex-number argument is the address of this complex number. 
For MTH$CLOG, complex-number specifies an F-floating number. 


Description 


The complex natural logarithm is computed as follows: 


CLOG(z) = (LOG(CABS(z)), ATAN2(i, r)) 


The routine descriptions for the D- and G-floating point versions of this routine 
are listed alphabetically under MTH$CxLOG. 


Condition Value Signaled 


SS$_ROPRAND Reserved operand. The MTH$CLOG routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH-34 


MTHSCLOG 


Example 


Examples of using MTH$CLOG from VAX MACRO (using both the CALLS and 
the CALLG instructions) appear in the introductory section of this manual. 


MTH-35 


MTH$CxLOG 


MTH$CxLOG—Complex Natural Logarithm 


Format 


Returns 


Arguments 


Description 


MTH-36 


The Complex Natural Logarithm routine returns the complex natural logarithm 
of a complex number. 


MTH$CDLOG_complex-natural-log ,complex-number 
MTH$CGLOG_ complex-natural-log ,complex-number 


Each of the above formats accepts one of the floating-point complex types as 
input. 


None. 


complex-natural-log 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access write only 
mechanism by reference 


Natural logarithm of the complex number specified by complex-number. The 
complex natural logarithm routines that have D-floating complex and G-floating 
complex input values write the address of the complex natural logarithm into 
complex-natural-log. For MTH$CDLOG, the complex-natural-log argument 
specifies a D-floating complex number. For MTH$CGLOG, the complex-natural- 
log argument specifies a G-floating complex number. 


complex-number 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access read only 
mechanism by reference 


Complex number whose complex natural logarithm is to be returned. This 
complex number has the form (r,1), where r is the real part and i is the imaginary 
part. The complex-number argument is the address of this complex number. 
For MTH$CDLOG, complex-number specifies a D-floating number. For 
MTH$CGLOG, complex-number specifies a G-floating number. 


The complex natural logarithm is computed as follows: 


CLOG(z) = (LOG(CABS(z)), ATAN2(i, r)) 


Condition Value Signaled 


Example 


MTH$_INVARGMAT 


SS$_FLTOVF_F 


SS$_ROPRAND 


QA AAQAAAAAaAN Sea Ga Oe 


MTH$CxLOG 


Invalid argument: r = 2 = 0. LIB$SIGNAL 
copies the floating-point reserved operand to 
the mechanism argument vector CHF$L_MCH_ 
SAVRO/R1. The result is the floating-point 
reserved operand unless you have written a 
condition handler to change CHF$L_MCH_ 
SAVRO/R1. 


Floating point overflow can occur. This condition 
value is signaled from MTH$CxABS when 
MTHS$CxABS overflows. 


Reserved operand. The MTH$CxLOG routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


This FORTRAN example forms the complex logarithm 
of a D-floating complex number by using MTHSCDLOG 
and the FORTRAN random number generator RAN. 


Declare Z and MTHSCDLOG as complex values. Then MTHSCDLOG 
will return the logarithm of Z: CALL MTH$CDLOG(Z NEW,2Z). 


Declare Z,2Z LOG, and MTHSDCMPLX as complex values, 
and R and I as real values. MTHSDCMPLX takes two real 
arguments and returns one complex number. 


Given a complex number Z, MTHSCDLOG(Z) returns the 
complex natural logarithm of 2Z. 


COMPLEX*16 Z,Z NEW,MTHSDCMPLX 


REAL*8 R,I 
3.1425637846746565 
7.43678469887 
MTHSDCMPLX(R, 1) 


R 
I 
vi 


Z is 
part 


= 9 


complex number (r,i) with real part "r" and imaginary 


TYPE *, ' The complex number z is’,z 


TYPE *, 
CALL MTH$CDLOG(Z NEW,2Z) 


TYPE *,’ The complex logarithm of',z,' is',Z NEW 
END 


MTH-37 


MTH$CxLOG 


This FORTRAN example program uses MTH$CDLOG by calling it as a procedure. 
The output generated by this program is as follows: 


The complex number z is (3.142563784674657,7.436784698870000) 
The complex logarithm of (3.142563784674657,7.436784698870000) is 
(2.088587642177504,1.170985519274141) 


MTH-38 


MTHS$CMPLX 


MTHSCMPLX—Complex Number Made from F-Floating-Point 


Format 


Returns 


Arguments 


Description 


The Complex Number Made from F-Floating-Point routine returns a complex 
number from two floating-point input values. 


MTH$CMPLX _real-part ,imaginary-part 


OpenVMS usage complex_number 


type F' floating complex 
access write only 
mechanism by value 


A complex number. MTH$CMPLX returns an F-floating complex number. 


real-part 

OpenVMS usage floating_point 
type F_floating 
access read only 
mechanism by reference 


Real part of a complex number. The real-part argument is the address of a 
floating-point number that contains this real part, r, of (r,i). For MTH$CMPLX, 
real-part specifies an F-floating number. 


imaginary-part 
OpenVMS usage _ floating_point 


type F_ floating 
access read only 
mechanism by reference 


Imaginary part of a complex number. The imag-parg argument is the address 
of a floating-point number that contains this imaginary part, 1, of (7,1). For 
MTH$CMPLX, imaginary-part specifies an F-floating number. 


The MTH$CMPLX routines return a complex number from two F-floating input 
values. The routine descriptions for the D- and G-floating point versions of this 
routine are listed alphabetically under MTH$xCMPLX. 


MTH-39 


MTHSCMPLX 


Condition Value Signaled 


Example 


MTH-40 


SS$_ ROPRAND Reserved operand. The MTH$CMPLX routine 


fo OOS Ge Fae CO ae 


C+ 
C 
C 
c- 


encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


This FORTRAN example forms two F-floating 
point complex numbers using MTHSCMPLX 
and the FORTRAN random number generator RAN. 


Declare Z and MTHSCMPLX as complex values, and R 
and I as real values. MTHSCMPLX takes two real 
F-floating point values and returns one COMPLEX*8 number. 


Note, since CMPLX is a generic name in FORTRAN, it would be 
sufficient to use CMPLX. 
CMPLX must be declare to be of type COMPLEX*8. 


Z = CMPLX(R,I) 


COMPLEX Z,MTHSCMPLX , CMPLX 


REAL*4 R,I 

INTEGER M 

M = 1234567 

R = RAN(M) 

I = RAN(M) 

Z = MTHSCMPLX(R,I) 


Z is a complex number (r,i) with real part "r" and 
imaginary part "i". 


TYPE *, ' The two input values are:',R,I 

TYPE *, ' The complex number z is’,z 

z = CMPLX(RAN(M) ,RAN(M)) 

TYPE *, ' ' 

TYPE *, ' Using the FORTRAN generic CMPLX with random R and I:’ 
TYPE *, ' The complex number z is’,z 

END 


This FORTRAN example program demonstrates the use of MTH$CMPLX. The 
output generated by this program is as follows: 


The two input values are: 0.8535407 0.2043402 
The complex number z is (0.8535407,0.2043402) 

Using the FORTRAN generic CMPLX with random R and I: 
The complex number z is (0.5722565,0.1857677) 


MTH$xCMPLX 


MTH$xCMPLX—Complex Number Made from D- or 


Format 


Returns 


Arguments 


G-Floating-Point 


The Complex Number Made from D- or G-Floating-Point routine returns a 
complex number from two D- or G-floating input values. 


MTH$DCMPLX_ complx ,real-part ,imaginary-part 
MTH$GCMPLX_ complx ,real-part ,imaginary-part 


Each of the above formats accepts one of floating-point complex types as input. 


None. 

complx 

OpenVMS usage complex_number 

type D_floating complex, G_floating complex 
access write only 

mechanism by reference 


The floating-point complex value of a complex number. The complex 
exponential functions that have D-floating complex and G-floating complex 
input values write the address of this floating-point complex value into 
complx. For MTH$DCMPLX, complx specifies a D-floating complex number. 
For MTH$GCMPLX, complx specifies a G-floating complex number. For 
MTH$CMPLX, complx is not used. 


real-part 

OpenVMS usage  floating_point 

type D_floating, G_floating 
access read only 

mechanism by reference 


Real part of a complex number. The real-part argument is the address of a 
floating-point number that contains this real part, r, of (r,i). For MTH$DCMPLX, 
real-part specifies a D-floating number. For MTH$GCMPLX, real-part specifies 
a G-floating number. 


imaginary-part 
OpenVMS usage  floating_point 


type D_flioating, G_floating 
access read only 
mechanism by reference 


Imaginary part of a complex number. The imag-parg argument is the 
address of a floating-point number that contains this imaginary part, i, of 
(ri). For MTH$DCMPLX, imaginary-part specifies a D-floating number. For 
MTH$GCMPLX, imaginary-part specifies a G-floating number. 


MTH-41 


MTH$xCMPLX 


Condition Value Signaled 


Example 


MTH—42 


SS$_ROPRAND Reserved operand. The MTH$xCMPLX routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand 1s a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Ct 
Cc This FORTRAN example forms two D-floating 
Cc point complex numbers using MTHSCMPLX 
C and the FORTRAN random number generator RAN. 
C 
C Declare Z and MTHSDCMPLX as complex values, and R 
C and I as real values. MTHSDCMPLX takes two real 
C D-floating point values and returns one 
C COMPLEX*16 number. 
C 
C= 
COMPLEX*16 Z 
REAL*8 R,I 
INTEGER M 
M = 1234567 
R = RAN(M) 
I = RAN(M) 
CALL MTHSDCMPLX(Z,R,I) 
C+ 
C Z is a complex number (r,i) with real part "r" and imaginary 
Cc part "i", 
C~ 


TYPE *, ' The two input values are:',R,I 
TYPE *, ' The complex number z is’ ,Z 
END 


This FORTRAN example demonstrates how to make a procedure call to 
MTH$DCMPLX. Notice the difference in the precision of the output generated. 


The two input values are: 0.8535407185554504 0.2043401598930359 
The complex number z is (0.8535407185554504,0.2043401598930359) 


MTH$CONJG 


MTHS$CONJG—Conjugate of a Complex Number (F-Floating Value) 


Format 


Returns 


Arguments 


Description 


The Conjugate of a Complex Number (F-Floating Value) routine returns the 
complex conjugate (1,-1) of a complex number (r,1) as an F-floating value. 


MTH$CONJG complex-number 


OpenVMS usage complex_number 


type F_floating complex 
access write only 
mechanism by value 


Complex conjugate of a complex number. MTH$CONJG returns an F-floating 
complex number. 


complex-number 
OpenVMS usage complex_number 


type F floating complex 
access read only 
mechanism by reference 


A complex number (r,i), where r and i are floating-point numbers. The complex- 
number argument is the address of this floating-point complex number. For 
MTH$CONJG, complex-number specifies an F-floating number. 


The MTH$CONJG routine returns the complex conjugate (r,-i) of a complex 
number (r,1) as an F-floating value. The routine descriptions for the D- 
and G-floating point versions of this routine are listed alphabetically under 


MTH$xCONJG. 


Condition Value Signaled 


SS$_ROPRAND Reserved operand. The MTH$CONJG routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


RATLI AQ 


MTH$xCONJG 


MTH$xCONJG—Conjugate of a Complex Number 


Format 


Returns 


Arguments 


The Conjugate of a Complex Number routine returns the complex conjugate (r,-1) 
of a complex number (r,i). 


MTH$DCONJG _ complex-conjugate ,complex-number 
MTH$GCONJG_ complex-conjugate ,complex-number 


Each of the above formats accepts one of the floating-point complex types as 
input. 


None. 


complex-conjugate 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access write only 
mechanism by reference 


The complex conjugate (r1,-i) of the complex number specified by complex- 
number. MTH$DCONJG and MTH$GCONJG write the address of this 
complex conjugate into complex-conjugate. For MTH$DCONJG, the complex- 
conjugate argument specifies the address of a D-floating complex number. For 
MTH$GCONJG, the complex-conjugate argument specifies the address of a 
G-floating complex number. 


complex-number 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access read only 
mechanism by reference 


A complex number (1,1), where r and i are floating-point numbers. The complex- 
number argument is the address of this floating-point complex number. 

For MTH$DCONJG, complex-number specifies a D-floating number. For 
MTH$GCONJG, complex-number specifies a G-floating number. 


Condition Value Signaled 


MTH—44 


SS$_ROPRAND Reserved operand. The MTH$xCONJG routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Example 


MTH$xCONJG 


C+ 
C This FORTRAN example forms the complex conjugate 
C of a G-floating complex number using MTHSGCONJG 
C and the FORTRAN random number generator RAN. 
7 | 
C Declare Z, Z NEW, and MTHSGCONJG as a complex values. 
C MTHSGCONJG will return the complex conjugate 
C value of Z: 2% NEW = MTHSGCONJG(Z). 
C- 
COMPLEX*16 Z,2 NEW,MTHSGCONJG 
COMPLEX*16 MTHSGCMPLX 
REAL*8 R,1,MTHSGREAL ,MTHSGIMAG 
INTEGER M 
M = 1234567 
Ct 


C Generate a random complex number with the 
C FORTRAN generic CMPLX. 


C= 
R = RAN(M) 
I = RAN(M) 
Z = MTHSGCMPLX(R,I) 


TYPE *, ‘ The complex number z is',z 
TYPE 1,MTHSGREAL(Z) ,MTHSGIMAG(Z) 
1 FORMAT(’ with real part ',F20.16,’ and imaginary part’,F20.16) 


TYPE. ego 
C+ 
C Compute the complex absolute value of 2. 
C- 


Z NEW = MTHS$GCONJG(Z) 

TYPE *, '’ The complex conjugate value of',z,' is’,Z NEW 
TYPE 1,MTHSGREAL(Z NEW) ,MTHSGIMAG(Z NEW) 

END 


This FORTRAN example demonstrates how to make a function call to 
MTH$GCONJG. Because G-floating numbers are used, the examples must 
be compiled with the statement “FORTRAN/G filename”. 


The output generated by this program is as follows: 


The complex number z is (0.853540718555450,0.204340159893036) 
with real part 0.8535407185554504 
and imaginary part 0.2043401598930359 


The complex conjugate value of 
(0.853540718555450,0.204340159893036) is 
(0.853540718555450,-0.204340159893036) 
with real part 0.8535407185554504 
and imaginary part -0.2043401598930359 


KATH AR 


MTH$xCOS 


MTH$xCOS—Cosine of Angle Expressed in Radians 


Format 


JSB Entries 


Returns 


Arguments 


Description 


hMATH—AA 


The Cosine of Angle Expressed in Radians routine returns the cosine of a given 
angle (in radians). 


MTH$COS _angle-in-radians 
MTH$DCOS = angle-in-radians 
MTH$GCOS = angle-in-radians 


Each of the above formats accepts one of the floating-point types as input. 


MTH$COS_R4 

MTH$DCOS_R7 

MTH$GCOS_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F_floating, D_floating, G_floating 
access write only 
mechanism by value 


Cosine of the angle. MTH$COS returns an F-floating number. MTH$DCOS 
returns a D-floating number. MTH$GCOS returns a G-floating number. 


angle-in-radians 
OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access read only 
mechanism by reference 


The angle in radians. The angle-in-radians argument is the address of a 
floating-point number. For MTH$COS, angle-in-radians is an F-floating 
number. For MTH$DCOS, angle-in-radians specifies a D-floating number. For 
MTH$GCOS, angle-in-radians specifies a G-floating number. 


See the MTH$xSINCOS routine for the algorithm used to compute the cosine. 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HCOS. 


MTH$xCOS 


Condition Value Signaled 


SS$_ROPRAND Reserved operand. The MTH$xCOS procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


AATLI AT 


MTH$xCOSD 


MTH$xCOSD—Cosine of Angle Expressed in Degrees 


Format 


JSB Entries 


Returns 


Arguments 


Description 


MTH—48 


The Cosine of Angle Expressed in Degrees routine returns the cosine of a given 
angle (in degrees). 


MTH$COSD angle-in-degrees 
MTH$DCOSD angle-in-degrees 
MTH$GCOSD angle-in-degrees 


Each of the above formats accepts one of the floating-point types as input. 


MTH$COSD_R4 

MTH$DCOSD_R7 

MTH$GCOSD_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


Cosine of the angle. MTH$COSD returns an F-floating number. MTH$DCOSD 
returns a D-floating number. MTH$GCOSD returns a G-floating number. 


angle-in-degrees 
OpenVMS usage floating_point 


type F floating, D_floating, G_floating 
access read only 
mechanism by reference 


Angle (in degrees). The angle-in-degrees argument is the address of a floating- 
point number. For MTH$COSD, angle-in-degrees specifies an F-floating 
number. For MTH$DCOSD, angle-in-degrees specifies a D-floating number. For 
MTH$GCOSD, angle-in-degrees specifies a G-floating number. 


See the MTH$SINCOSD routine for the algorithm used to compute the cosine. 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HCOSD. 


Condition Value Signaled 


SS$_ROPRAND 


MTH$xCOSD 


Reserved operand. The MTH$xCOSD procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


hKATH—AQ 


- MTH$xCOSH 


MTH$xCOSH—Hyperbolic Cosine 


Format 


Returns 


Arguments 


Description 


MTH—50 


The Hyperbolic Cosine routine returns the hyperbolic cosine of the input value. 


MTH$COSH _floating-point-input-value 
MTH$DCOSH _ floating-point-input-value 
MTH$GCOSH _floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type F' floating, D_floating, G_floating 
access write only 
mechanism by value 


The hyperbolic cosine of the input value floating-point-input-value. 
MTH$COSH returns an F-floating number. MTH$DCOSH returns a D-floating 
number. MTH$GCOSH returns a G-floating number. 


floating-point-input-value 
OpenVMS usage _floating_point 


type F floating, D_floating, G_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of 
this input value. For MTH$COSH, floating-point-input-value specifies an 
F-floating number. For MTH$DCOSH, floating-point-input-value specifies a 
D-floating number. For MTH$GCOSH, floating-point-input-value specifies a 
G-floating number. 


Computation of the hyperbolic cosine depends on the magnitude of the input 
argument. The range of the function is partitioned using four data-type- 
dependent constants: a(z), b(z), and c(z). The subscript z indicates the data 

type. The constants depend on the number of exponent bits (e) and the number of 
fraction bits (f) associated with the data type (2). 


The values of e and f are: 


z f 

F 8 24 
D 8 56 
G 11 53 


MTH$xCOSH 


The values of the constants in terms of e and f are: 


Variable Value 
a(z) o(— f/2) 
b(z) CEILINGI(f + 1) /2 * In(2)] 


c(z) (2°-*) « In(2) 


Based on the above definitions, zCOSH(X) is computed as follows: 


Value of X 


|X| <a(z) 
a(z) < I XI <.25 
25< IXI <b(z) 
b(z) < IXI <c(z) 
e(z) < Ix 


Value Returned 


Computed using a power series expansion in |X |? 
(2zEXP(|X|) + 1/2zEXP(|X]))/2 

zEXP(|X|)/2 

Overflow occurs 


This routine description for the H-floating point value is listed alphabetically 


under MTH$HCOSH. 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$xCOSH procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in Math Library: the 
absolute value of floating-point-input-value is 
greater than about yyy; LIB$SIGNAL copies the 
reserved operand to the signal mechanism vector. 
The result is the reserved operand -0.0 unless a 
condition handler changes the signal mechanism 
vector. 


The values of yyy are: 
MTH$COSH—88.722 


MTH$DCOSH—88.722 
MTH$GCOSH—709.782 


MTH—51 


MTHSCSIN 


MTH$CSIN—Sine of a Complex Number (F-Floating Value) 


The Sine of a Complex Number (F-Floating Value) routine returns the sine of a 
complex number (r,i) as an F-floating value. 


Format 
MTH$CSIN complex-number 
Returns 
OpenVMS usage complex_number 
type F floating complex 
access write only 
mechanism by value 
Complex sine of the complex number. MTH$CSIN returns an F-floating complex 
number. 
Arguments 
complex-number 
OpenVMS usage complex_number 
type F floating complex 
access read only 
mechanism by reference 
A complex number (r,i), where r and i are floating-point numbers. The complex- 
number argument is the address of this complex number. For MTH$CSIN, 
complex-number specifies an F-floating complex number. 
Description 


The complex sine is computed as follows: 


complex — sine = (SIN(r) * COSH (2), COS(r) « SIN A(z)) 


The routine descriptions for the D- and G-floating point versions of this routine 
are listed alphabetically under MTH$CxSIN. 


Condition Values Signaled 


SS$_ROPRAND Reserved operand. The MTH$CSIN procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$ FLOOVEMAT Floating-point overflow in Math Library: the 
absolute value of i is greater than about 88.029 
for F-floating values. 


MTH-52 


MTH$CxSIN 


MTH$CxSIN—Sine of a Complex Number 


Format 


Returns 


Arguments 


Description 


The Sine of a Complex Number routine returns the sine of a complex number (r,i). 


MTH$CDSIN complex-sine ,complex-number 
MTH$CGSIN complex-sine ,complex-number 


Each of the above formats accepts one of the floating-point complex types as 
input. 


None. 


complex-sine 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access write only 
mechanism by reference 


Complex sine of the complex number. The complex sine routines with D-floating 
complex and G-floating complex input values write the complex sine into this 
complex-sine argument. For MTH$CDSIN, complex-sine specifies a D-floating 
complex number. For MTH$CGSIN, complex-sine specifies a G-floating complex 
number. 


complex-number 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access read only 
mechanism by reference 


A complex number (1,1), where r and i are floating-point numbers. The complex- 
number argument is the address of this complex number. For MTH$CDSIN, 
complex-number specifies a D-floating complex number. For MTH$CGSIN, 
complex-number specifies a G-floating complex number. 


The complex sine is computed as follows: 


complex — sine = (SIN(r) x COSH (2), COS(r) « SINH(:2)) 


MTH-53 


MTH$CxSIN 


Condition Values Signaled 


SS$_ROPRAND Reserved operand. The MTH$CxSIN procedure 


encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$ FLOOVEMAT Floating-point overflow in Math Library: the 


Example 


SO Ce a Sa ee 


C+ 
C 
‘ge 


absolute value of i is greater than about 88.029 
for D-floating values, or greater than about 
‘709.089 for G-floating values. 


This FORTRAN example forms the complex 
sine of a G-floating complex number using 
MTHSCGSIN and the FORTRAN random number 
generator RAN. 


Declare Z and MTHSCGSIN as complex values. 
MTHSCGSIN will return the sine value 
of Z: CALL MTHSCGSIN(Z NEW,Z) 


COMPLEX*16 2,2 NEW 
COMPLEX*16 DCMPLX 
REAL*8 R,I 

INTEGER M 

M = 1234567 


Generate a random complex number with the 
FORTRAN generic DCMPLX. 


R = RAN(M) 
I = RAN(M) 
Z = DCMPLX(R,I) 


Z is a complex number (r,i) with real part "r" and 
imaginary part "i". 


TYPE *, ' The complex number z is',z 
TER Re. od 


Compute the complex sine value of Z. 


CALL MTHSCGSIN(Z_NEW,Z) 
TYPE *, ' The complex sine value of',z,’ is’,Z NEW 
END 


This FORTRAN example demonstrates a procedure call to MTH$CGSIN. Because 
this program uses G-floating numbers, it must be compiled with the statement 
“FORTRAN/G filename”. 


MTH-54 


MTH$CxSIN 


The output generated by this program is as follows: 


The complex number z is (0.853540718555450,0.204340159893036) 
The complex sine value of (0.853540718555450,0.204340159893036) is 
(0.769400835484975,0.135253340912255) 


MTH—55 


MTH$CSQRT 


MTHS$CSQRT—Complex Square Root (F-Floating Value) 


Format 


Returns 


Arguments 


Description 


MTH-56 


The Complex Square Root (F-Floating Value) routine returns the complex square 
root of a complex number (1,1). 


MTH$CSQRT_ complex-number 


OpenVMS usage complex_number 


type F_ floating complex 
access write only 
mechanism by value 


The complex square root of complex-number. MTH$CSQRT returns an F- 
floating number. 


complex-number 
OpenVMS usage complex_number 


type F’_floating complex 
access read only 
mechanism by reference 


Complex number (r,i). The complex-number argument contains the address 
of this complex number. For MTH$CSQRT, complex-number specifies an 
F-floating number. 


The complex square root is computed as follows. 


First, calculate ROOT and Q using the following equations: 
ROOT = SQRT((ABS(r) + CABS (r,z)) /2) 
Q =i/(2* ROOT) 


Then, the complex result is given as follows: 


r j CSQRT((r,i)) 
>0 Any (ROOT,Q) 
<0 <0 (-Q,-ROOT) 


The routine descriptions for the D- and G-floating point versions of this routine 
are listed alphabetically under MTH$CxSQRT. 


MTH$CSQRT 


Condition Value Signaled 


SS$_ FLTOVF_F Floating point overflow can occur. 


SS$_ROPRAND Reserved operand. The MTH$CSQRT procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH-57 


MTH$CxSQRT 


MTH$CxSQRT—Complex Square Root 


Format 


Returns 


Arguments 


Description 


MTH-58 


The Complex Square Root routine returns the complex square root of a complex 
number (r,1). 


MTH$CDSQRT _ complex-square-root ,complex-number 
MTH$CGSQRT _ complex-square-root ,complex-number 


Each of the above formats accepts one of the floating-point complex types as 
input. 


None. 


complex-square-root 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access write only 
mechanism by reference 


Complex square root of the complex number specified by complex-number. 
The complex square root routines that have D-floating complex and G-floating 
complex input values write the complex square root into complex-square- 
root. For MTH$CDSQRT, complex-square-root specifies a D-floating complex 
number. For MTH$CGSQRT, complex-square-root specifies a G-floating 
complex number. 


complex-number 
OpenVMS usage complex_number 


type D_floating complex, G_floating complex 
access read only 
mechanism by reference 


Complex number (1,1). The complex-number argument contains the address 
of this complex number. For MTH$CDSQRT, complex-number specifies a D- 
floating number. For MTH$CGSQRT, complex-number specifies a G-floating 
number. 


The complex square root is computed as follows. 


First, calculate ROOT and Q using the following equations: 
ROOT = SQRT((ABS(r) + CABS(r, 2)) /2) 


Q =i/(2* ROOT) 


Then 


r 
>0 
<0 
<0 


MTH$CxSQRT 


, the complex result is given as follows: 


j CSQRT((r,i)) 


any (ROOT.Q) 
>0 (Q,ROOT) 
<0 (-Q,-ROOT) 


Condition Value Signaled 


Example 


SS$_FLTOVF_F Floating point overflow can occur. 
SS$_ ROPRAND Reserved operand. The MTH$CxSQRT procedure 


+ 


MAMA AAAAAQ 


Cr 


C- 


encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


This FORTRAN example forms the complex square 
root of a D-floating complex number using 
MTHSCDSQRT and the FORTRAN random number 
generator RAN. 


Declare Z and Z NEW as complex values. MTH$SCDSQRT 
will return the complex square root of 
Z3 CALL MTHSCDSQRT(Z_NEW,Z). 


COMPLEX*16 2,2 NEW 
COMPLEX*16 DCMPLX 
INTEGER M 

M = 1234567 


Generate a random complex number with the 
FORTRAN generic CMPLX. 


Z = DCMPLX(RAN(M) ,RAN(M)) 


Z is a complex number (r,i) with real part "r“ and imaginary 
part "i". 


TYPE *, ’ The complex number z is’,z 
TYPE *, ” * 


Compute the complex complex square root of 2. 


CALL MTHSCDSQRT(Z NEW, Z) 
TYPE *, ' The complex square root of’,z,' is’,Z NEW 
END 
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MTH$CxSQRT 


This FORTRAN example program demonstrates a procedure call to 
MTH$CDSQRT. The output generated by this program is as follows: 


The complex number z is (0.8535407185554504,0.2043401598930359) 
The complex square root of (0.8535407185554504,0.2043401598930359) is 
(0.9303763973040062,0.1098158554350485) 
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MTHS$CVT_x_x 


MTHSCVT_x_x—Convert One Double-Precision Value 


The Convert One Double-Precision Value routines convert one double-precision 
value to the destination data type and return the result as a function value. 
MTH$CVT_D_G converts a D-floating value to G-floating and MTH$CVT_G_D 
converts a G-floating value to a D-floating value. 


Format 
MTH$CVT_D_G_ floating-point-input-val 
MTH$CVT_G_D _ floating-point-input-val 
Returns 
OpenVMS usage  floating_point 
type G_floating, D_floating 
access write only 
mechanism by value 
The converted value. MTH$CVT_D_G returns a G-floating value. MTH$CVT_G_ 
D returns a D-floating value. 
ARGUMENT 


floating-point-input-val 
OpenVMS usage  floating_point 


type D_floating, G_floating 
access read only 
mechanism by reference 


The input value to be converted. The floating-point-input-val argument 
is the address of this input value. For MTH$CVT_D_G, the floating-point- 
input-val argument specifies a D-floating number. For MTH$CVT_G_D, the 
floating-point-input-val argument specifies a G-floating number. 


Description 


These procedures are designed to function as hardware conversion instructions. 
They fault on reserved operands. If floating-point overflow is detected, an error 
is signaled. If floating-point underflow is detected and floating-point underflow is 
enabled, an error is signaled. 
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MTHSCVT_x_x 


Condition Values Signaled 
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SS$_ROPRAND 


MTH$_FLOOVEMAT 
MTH$_FLOUNDMAT 


Reserved operand. The MTH$CVT_x_x 
procedure encountered a floating-point reserved 
operand due to incorrect user input. A floating- 
point reserved operand is a floating-point datum 
with a sign bit of 1 and a biased exponent of 0. 
Floating-point reserved operands are reserved for 
future use by Digital. 


Floating-point overflow in Math Library. 
Floating-point underflow in Math Library. 


MTHS$CVT_xA_xA 


MTH$CVT_xA_xA—Convert an Array of Double-Precision Values 


Format 


Returns 


Arguments 


The Convert an Array of Double-Precision Values routines convert a contiguous 
array of double-precision values to the destination data type and return the 
results as an array. MTH$CVT_DA_GA converts D-floating values to G-floating 
and MTH$CVT_GA_DA converts G-floating values to D-floating. 


MTH$CVT_DA_GA _ floating-point-input-array ,floating-point-dest-array [,array-size] 
MTH$CVT_GA_DA _ floating-point-input-array ,floating-point-dest-array [,array-size] 


OpenVMS usage HEADONLY 


MTH$CVT_DA_GA and MTH$CVT_GA_DA return the address of the output 
array to the floating-point-dest-array argument. 


floating-point-input-array 
OpenVMS usage _ floating_point 


type D_floating, G_floating 
access read only 
mechanism by reference, array reference 


Input array of values to be converted. The floating-point-input-array argument 
is the address of an array of floating-point numbers. For MTH$CVT_DA_GA, 
floating-point-input-array specifies an array of D-floating numbers. For 
MTH$CVT_GA_DA, floating-point-input-array specifies an array of G-floating 
numbers. 


floating-point-dest-array 
OpenVMS usage  floating_point 


type G_floating, D_floating 
access write only 
mechanism by reference, array reference 


Output array of converted values. The floating-point-dest-array argument 
is the address of an array of floating-point numbers. For MTH$CVT_DA_ 

GA, floating-point-dest-array specifies an array of G-floating numbers. For 
MTH$CVT_GA_DA, floating-point-dest-array specifies an array of D-floating 
numbers. | 


array-size 

OpenVMS usage longword_signed 
type longword (signed) 
access read only 
mechanism by reference 


Number of array elements to be converted. The default value is 1. The array- 
size argument is the address of a longword containing this number of elements. 
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MTHS$CVT_xA_xA 


Description 


These procedures are designed to function as hardware conversion instructions. 
They fault on reserved operands. If floating-point overflow is detected, an error 
is signaled. If floating-point underflow is detected and floating-point underflow is 
enabled, an error is signaled. 


Condition Values Signaled 
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SS$ ROPRAND Reserved operand. The MTH$CVT_xA_xA 
procedure encountered a floating-point reserved 
operand due to incorrect user input. A floating- 
point reserved operand is a floating-point datum 
with a sign bit of 1 and a biased exponent of 0. 
Floating-point reserved operands are reserved for 
future use by Digital. 


MTH$_FLOOVEMAT Floating-point overflow in Math Library. 
MTH$_FLOUNDMAT Floating-point underflow in Math Library. 


MTH$xEXP 


MTH$xEXP—Exponential 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Exponential routine returns the exponential of the input value. 


MTH$EXP _ floating-point-input-value 
MTH$DEXP _ floating-point-input-value 
MTH$GEXP _floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


MTH$EXP_R4 

MTH$DEXP_R6 

MTH$GEXP_R6 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


The exponential of floating-point-input-value. MTH$EXP returns an F-floating 
number. MTH$DEXP returns a D-floating number. MTH$GEXP returns a 
G-floating number. 


floating-point-input-value 
OpenVMS usage  floating_point 


type F_floating, D_floating, G_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of 
a floating-point number. For MTH$EXP, floating-point-input-value specifies 
an F-floating number. For MTH$DEXP, floating-point-input-value specifies 

a D-floating number. For MTH$GEXP, floating-point-input-value specifies a 
G-floating number. 


The exponential of x is computed as: 


Value of x Value Returned 
X > c(z) Overflow occurs 
X< —c(z) 0 
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MTH$xEXP 


Value of x Value Returned 


IX], <2-F+D 4 
Otherwise oY 4 QU 4 QW 


where: Y = INTEGER(s « In2(E)) V = FRAC(za * In2(E)) « 16 
U = INTEGER(V)/16 W = FRAC(V)/16 2” = polynomial approximation of 
degree 4, 8, or 8 for z = F, D, or G. 


See also the section on the hyperbolic cosine for definitions of f and c(z). 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HEXP. 


Condition Values Signaled 
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SS$_ROPRAND 


MTH$_FLOOVEMAT 


MTH$_FLOUNDMAT 


Reserved operand. The MTH$xEXP routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in Math Library: 
floating-point-input-value is greater than 
yyy; LIB$SIGNAL copies the reserved operand to 
the signal mechanism vector. The result is the 
reserved operand -0.0 unless a condition handler 
changes the signal mechanism vector. 


The values of yyy are approximately: 


MTH$EXP—88.029 
MTH$DEXP—88.029 
MTH$GEXP—709.089 


Floating-point underflow in Math Library: 
floating-point-input-value is less than or 
equal to yyy and the caller (CALL or JSB) has 
set hardware floating-point underflow enable. 
The result is set to 0.0. If the caller has not 
enabled floating-point underflow (the default), a 
result of 0.0 is returned but no error is signaled. 


The values of yyy are approximately: 


MTH$EXP— — 88.722 
MTH$DEXP— — 88.722 
MTH$GEXP— — 709.774 


Example 


MTH$xEXP 


IDENTIFICATION DIVISION. 
PROGRAM-ID. § FLOATING POINT. 
* 
* Calls MTHSEXP using a Floating Point data type. 
* Calls MTHSDEXP using a Double Floating Point data type. 
* 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 FLOAT PT COMP-1. 
01 ANSWER F COMP-1. 
01 DOUBLE PT  COMP-2. 
01 ANSWER D COMP-2. 
PROCEDURE DIVISION. 
PO. 
MOVE 12.34 TO FLOAT PT. 
MOVE 3.456 TO DOUBLE PT. 


CALL "MTHSEXP" USING BY REFERENCE FLOAT PT GIVING ANSWER F. 
DISPLAY " MTHSEXP of ", FLOAT PT CONVERSION, " is ", 
ANSWER F CONVERSION. 


CALL "MTH$DEXP" USING BY REFERENCE DOUBLE PT GIVING ANSWER_D. 
DISPLAY “ MTHSDEXP of ", DOUBLE PT CONVERSION, " is ", 

7 ANSWER_D CONVERSION . 
STOP RUN. 


This sample program demonstrates calls to MTH$EXP and MTH$DEXP from 
COBOL. 
The output generated by this program is as follows: 


MTHSEXP of 1.234000E+01 is 2.286620E+05 
MTHSDEXP of 3.456000000000000E+00 is 
3.168996280537917E+01 
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MTHSHACOS 


MTHS$HACOS—Arc Cosine of Angle Expressed in Radians 
(H-Floating Value) 


Given the cosine of an angle, the Arc Cosine of Angle Expressed in Radians 
(H-Floating Value) routine returns that angle (in radians) in H-floating-point 


precision. 
Format 
MTH$HACOS _sh-radians ,cosine 
JSB Entries 
MTH$HACOS_R8 
Returns 
None. 
Arguments 
h-radians 
OpenVMS usage _ floating_point 
type H_floating 
‘access write only 
mechanism by reference 
Angle (in radians) whose cosine is specified by cosine. The h-radians argument 
is the address of an H-floating number that is this angle. MTH$HACOS writes 
the address of the angle into h-radians. 
cosine 
OpenVMS usage  floating_point 
type H_floating 
access read only 
mechanism by reference 
The cosine of the angle whose value (in radians) is to be returned. The cosine 
argument is the address of a floating-point number that is this cosine. The 
absolute value of cosine must be less than or equal to 1. For MTH$HACOS, 
cosine specifies an H-floating number. 
Description 


The angle in radians whose cosine is X is computed as: 


Value of Cosine Value Returned 


0 nm /2 
1 0 
—1 T 
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Value of Cosine Value Returned 


MTHS$HACOS 


0<X<1 zATAN(zSQRT(1— X”)/X), where zATAN and zSQRT are the 
Math Library arc tangent and square root routines, respectively, 
of the appropriate data type 

-1<X<0 zATAN(zSQRT(1— X*)/X)+-x 

1< |X| The error MTH$_INVARGMAT is signaled 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_INVARGMAT 


Reserved operand. The MTH$xACOS routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. The absolute value of cosine 
is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF$L_MCH_SAVRO/R1. 
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MTHSHACOSD 


MTHSHACOSD—Arc Cosine of Angle Expressed in Degrees 


Format 


JSB Entries 


Returns 


Arguments 


Description 


MTH—70 


(H-Floating Value) 


Given the cosine of an angle, the Arc Cosine of Angle Expressed in Degrees 
(H-Floating Value) routine returns that angle (in degrees) as an H-floating value. 


MTH$HACOSD h-degrees ,cosine 


MTH$HACOSD_R8 


None. 

h-degrees 

OpenVMS usage _floating_point 
type H_floating 
access write only 
mechanism by reference 


Angle (in degrees) whose cosine is specified by cosine. The h-degrees argument 
is the address of an H-floating number that is this angle. MTH$HACOSD writes 
the address of the angle into h-degrees. 


cosine 

OpenVMS usage _ floating_point 
type H_floating 
access read only 
mechanism by reference 


Cosine of the angle whose value (in degrees) is to be returned. The cosine 
argument is the address of a floating-point number that is this cosine. The 
absolute value of cosine must be less than or equal to 1. For MTH$HACOSD, 
cosine specifies an H-floating number. 


The angle in degrees whose cosine is X is computed as: 


Value of Cosine Angle Returned 


0 90 

1 0 

—1 180 

0<X<1 zATAN D(zSQRT(1 — X7)/X), where zATAND and zSQRT 


are the Math Library arc tangent and square root routines, 
respectively, of the appropriate data type 


Value of Cosine Angle Returned 


MTHSHACOSD 


-1<X<0 zATAN D(zSQRT(1— X*)/X) + 180 
1 < |X| The error MTH$_ INVARGMAT is signaled 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_INVARGMAT 


Reserved operand. The MTH$xACOSD routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. The absolute value of cosine 
is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_ SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF $L_MCH_SAVRO/R1. 
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MTHSHASIN 


MTHS$HASIN—Arc Sine in Radians (H-Floating Value) 


Given the sine of an angle, the Arc Sine in Radians (H-Floating Value) routine 
returns that angle (in radians) as an H-floating value. 


Format 
MTH$HASIN _ h-radians ,sine 
JSB Entries 
MTH$HASIN_R8 
Returns 
None. 
Arguments 
h-radians 
OpenVMS usage _ floating_point 
type H_floating 
access write only 
mechanism by reference 
Angle (in radians) whose sine is specified by sine. The h-radians argument is 
the address of an H-floating number that is this angle. MTH$HASIN writes the 
address of the angle into h-radians. 
sine 
OpenVMS usage _ floating_point 
type H_floating 
access read only 
mechanism by reference 
The sine of the angle whose value (in radians) is to be returned. The sine 
argument is the address of a floating-point number that is this sine. The absolute 
value of sine must be less than or equal to 1. For MTH$HASIN, sine specifies 
an H-floating number. 
Description 


The angle in radians whose sine is X is computed as: 


Value of Sine Angle Returned 

0 0 

1 n /2 

—1 —n /2 

0<|X|<1 zATAN(X/zSQRT(1— X?)), where zATAN and zSQRT are the 


Math Library arc tangent and square root routines, respectively, 
of the appropriate data type 


1 < |X| The error MTH$_INVARGMAT is signaled 
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Condition Values Signaled 


SS$_ROPRAND 


MTH$_INVARGMAT 


MTH$HASIN 


Reserved operand. The MTH$xASIN routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. The absolute value of sine 

is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF$L_MCH_SAVRO/R1. 
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MTHS$HASIND 


MTH$HASIND—Arc Sine in Degrees (H-Floating Value) 


Format 


JSB Entries 


Returns 


Arguments 


Description 
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Given the sine of an angle, the Arc Sine in Degrees (H-Floating Value) routine 
returns that angle (in degrees) as an H-floating value. 


MTH$HASIND  h-degrees ,sine 


MTHS$HASIND_R8 


None. 

h-degrees 

OpenVMS usage floating_point 
type H_floating 
access write only 
mechanism by reference 


Angle (in degrees) whose sine is specified by sine. The h-degrees argument is 
the address of an H-floating number that is this angle. MTH$HASIND writes the 
address of the angle into h-degrees. 


sine 

OpenVMS usage  floating_point 
type H_fioating 
access read only 
mechanism by reference 


Sine of the angle whose value (in degrees) is to be returned. The sine argument 
is the address of a floating-point number that is this sine. The absolute value 
of sine must be less than or equal to 1. For MTH$HASIND, sine specifies an 
H-floating number. 


The angle in degrees whose sine is X is computed as: 


Value of Sine Value Returned 

0 0 

1 90 

—1 —90 

0<(|X|<1 zATAN D(X/zSQRT(1 — X*)), where zATAND and zSQRT 


are the Math Library arc tangent and square root routines, 
respectively, of the appropriate data type 


1< |X The error MTH$_INVARGMAT is signaled 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_INVARGMAT 


MTHSHASIND 


Reserved operand. The MTH$xASIND routine 
encountered a floating point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. The absolute value of sine 

is greater than 1. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF $L_MCH_SAVRO/R1. 
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MTH$HATAN 


MTHSHATAN—Arc Tangent in Radians (H-Floating Value) 


Format 


JSB Entries 


Returns 


Arguments 


Description 
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Given the tangent of an angle, the Arc Tangent in Radians (H-Floating Value) 
routine returns that angle (in radians) as an H-floating value. 


MTH$HATAN _h-radians ,tangent 


MTHS$HATAN_R8 


None. 

h-radians 

OpenVMS usage  floating_point 
type H_floating 
access write only 
mechanism by reference 


Angle (in radians) whose tangent is specified by tangent. The h-radians 
argument is the address of an H-floating number that is this angle. 
MTH$HATAN writes the address of the angle into h-radians. 


tangent 

OpenVMS usage _ floating_point 
type H_floating 
access read only 
mechanism by reference 


The tangent of the angle whose value (in radians) is to be returned. The tangent 
argument is the address of a floating-point number that is this tangent. For 
MTH$HATAN, tangent specifies an H-floating number. 


In radians, the computation of the are tangent function is based on the following 
identities: 
arctan(X) = X — X3/3+ X°/5—X"/7+... 
arctan(X) = X + X + Q(X%), 
where Q(Y) = —Y/3+ Y2/5 —Y3°/7 +... 
arctan(X) = X * P(X”), 
where P(Y) =1-—Y/3+Y2/5-Y°/7+4... 
arctan(X) = 7/2 — arctan(1/X) 
arctan(X) = arctan(A) + arctan((X — A)/(1+ A* X)) 
for any real A 


MTHSHATAN 


The angle in radians whose tangent is X is computed as: 


Value of X 


0<X<3/32 
3/32 < X<11 


1i< X 
X <0 


Condition Value Signaled 


SS$_ROPRAND 


Angle Returned 

X+X+ Q(X?) | 

ATAN(A) + V * (P(V2)), where A and ATAN(A) are 
chosen by table lookup and V = (X — A)/(1+ A* X) 
n/2—W *(P(W7)) where W = 1/X 

—zATAN(|X}) 


Reserved operand. The MTH$xATAN routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 
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MTHS$HATAND 


MTH$HATAND—Arc Tangent in Degrees (H-Floating Value) 


Given the tangent of an angle, the Arc Tangent in Degrees (H-Floating Value) 
routine returns that angle (in degrees) as an H-floating point value. 


Format 
MTH$HATAND = h-degrees ,tangent 
JSB Entries 
MTH$HATAND_R8 
Returns 
None. 
Arguments 
h-degrees 
OpenVMS usage _ floating_point 
type H_floating 
access write only 
mechanism by reference 
Angle (in degrees) whose tangent is specified by tangent. The h-degrees 
argument is the address of an H-floating number that is this angle. 
MTH$HATAND writes the address of the angle into h-degrees. 
tangent 
OpenVMS usage _ floating_point 
type H_floating 
access read only 
mechanism by reference 
The tangent of the angle whose value (in degrees) is to be returned. The tangent 
argument is the address of a floating-point number that is this tangent. For 
MTH$HATAND, tangent specifies an H-floating number. 
Description 


The computation of the arc tangent function is based on the following identities: 
arctan(X) = 180/m * (X — X°/3 + X°/5 — X"/7+...) 
arctan(X) = 64*« X+ X + Q(X7), 
where Q(Y) = 180/z « [(1 — 64 « 7/180) — Y/3+ 
Y72/5- Y3/7+Y4/9...] 
arctan(X) = X * P(X?), 
where P(Y) = 180/m*|[1- Y/3 + Y2/5 — Y?/7+ 
Y*/9...| 
arctan(X) = 90 — arctan(1/X) 
arctan(X) = arctan(A) + arctan((X — A)/(1+ A * X)) 
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MTHSHATAND 


The angle in degrees whose tangent is X is computed as: 


Tangent 
X <3/32 
3/32 < X<11 


11< X 
xX <0 


Condition Value Signaled 


SS$_ROPRAND 


Angle Returned 


644 X+ X* Q(X?) 

ATAN D(A) + V + P(V7), where A and ATAND(A) are 
chosen by table lookup and V = (X — A)/(1+ A * X) 
90 — W «(P(W7)), where W = 1/X 

-zATAND(|X]) 


Reserved operand. The MTH$xATAND routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 
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MTH$HATAN2 


MTH$HATAN2—Arc Tangent in Radians (H-Floating Value) with Two 


Format 


Returns 


Arguments 


Description 


MTH-80 


Arguments 


Given sine and cosine, the Arc Tangent in Radians (H-Floating Value) with Two 
Arguments routine returns the angle (in radians) as an H-floating value whose 
tangent is given by the quotient of sine and cosine, (sine/cosine). 


MTH$HATAN2_h-radians ,sine ,cosine 


None. 

h-radians 

OpenVMS usage  floating_point 
type H_floating 
access write only 
mechanism by reference 


Angle (in radians) whose tangent is specified by (sine/cosine). The h- 
radians argument is the address of an H-floating number that is this angle. 
MTH$HATAN2 writes the address of the angle into h-radians. 


sine 

OpenVMS usage  floating_point 
type H_floating 
access read only 
mechanism by reference 


Dividend. The sine argument is the address of a floating-point number that is 
this dividend. For MTH$HATAN2, sine specifies an H-floating number. 


cosine 

OpenVMS usage floating point 
type H_floating 
access read only 
mechanism by reference 


Divisor. The cosine argument is the address of a floating-point number that is 
this divisor. For MTH$HATAN2, cosine specifies an H-floating number. 


The angle in radians whose tangent is Y/X is computed as follows, where f is 
defined in the description of MTH$zCOSH: 


Value of Input Arguments Angle Returned 
X=OorY/X> 2F+) n/2* (signY) 
X>0 and Y/X< aft) zATAN(Y/X) 


Value of Input Arguments 


X <Oand Y/X< 2Ftv 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_INVARGMAT 


MTHSHATAN2 


Angle Returned 
a *(stgnY) + zATAN(Y/X) 


Reserved operand. The MTH$HATAN2 routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. Both cosine and sine are 
zero. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_MCH_SAVRO/R1. The result 

is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


MTH-81 


MTHSHATAND2 


MTHSHATAND2—Arc Tangent in Degrees (H-Floating Value) with Two 


Format 


Returns 


Arguments 


Description 


MTH-82 


Arguments 


Given sine and cosine, the Arc Tangent in Degrees (H-Floating Value) with Two 
Arguments routine returns the angle (in degrees) whose tangent is given by the 
quotient of sine and cosine, (sine/cosine). 


MTH$HATAND2_h-degrees ,sine ,cosine 


None. 

h-degrees 

OpenVMS usage floating_point 
type H_floating 
access write only 
mechanism by reference 


Angle (in degrees) whose tangent is specified by (sine/cosine). The h- 
degrees argument is the address of an H-floating number that is this angle. 
MTH$HATAND2 writes the address of the angle into h-degrees. 


sine 

OpenVMS usage floating_point 
type H_floating 
access read only 
mechanism by reference 


Dividend. The sine argument is the address of a floating-point number that is 
this dividend. For MTH$HATAND2, sine specifies an H-floating number. 


cosine 

OpenVMS usage  floating_point 
type H_floating 
access read only 
mechanism by reference 


Divisor. The cosine argument is the address of a floating-point number that is 
this divisor. For MTH$HATAND2, cosine specifies an H-floating number. 


The angle in degrees whose tangent is Y/X is computed below. The value of fis 
defined in the description of MTH$zCOSH. 


Value of Input Arguments Angle Returned 
X=OorY/X> 2e+D 90 + (stgnY) 
X>Oand Y/X< 2+) zATAN D(Y/X) 


Value of Input Arguments 


X <Oand Y/X< 20 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_INVARGMAT 


MTHS$HATAND2 


Angle Returned 
180 * (stgnY) + zATAND(Y/X) 


Reserved operand. The MTH$HATAND2 routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument. Both cosine and sine are 
zero. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_ MCH SAVRO/R1. The result 

is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


KATH RQ 


MTHSHATANH 


MTHSHATANH—Hyperbolic Arc Tangent (H-Floating Value) 


Given the hyperbolic tangent of an angle, the Hyperbolic Arc Tangent (H-Floating 
Value) routine returns the hyperbolic arc tangent (as an H-floating Value) of that 


angle. 
Format 
MTH$HATANH _ h-atanh ,hyperbolic-tangent 
Returns 
None. 
i 
Arguments 
h-atanh 
OpenVMS usage floating_point 
type H_floating 
access write only 
mechanism by reference 


Hyperbolic arc tangent of the hyperbolic tangent specified by hyperbolic- 
tangent. The h-atanh argument is the address of an H-floating number that is 
this hyperbolic arc tangent. MTH$HATANH writes the address of the hyperbolic 
arc tangent into h-atanh. 


hyperbolic-tangent 
OpenVMS usage _floating_point 


type H_floating 
access read only 
mechanism by reference 


Hyperbolic tangent of an angle. The hyperbolic-tangent argument is 

the address of a floating-point number that is this hyperbolic tangent. For 

MTH$HATANH, hyperbolic-tangent specifies an H-floating number. 
Description 


The hyperbolic arc tangent function is computed as follows: 


Value of x Value Returned 
|X| <1 zATANH(X) = 2zLOG((X + 1)/(X — 1))/2 
|\X|>1 An invalid argument is signaled 


MTH-84 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_INVARGMAT 


MTHSHATANH 


Reserved operand. The MTH$xATANH routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Invalid argument: | XI > 1. LIB$SIGNAL 
copies the floating-point reserved operand to 
the mechanism argument vector CHF$L_MCH_ 
SAVRO/R1. The result is the floating-point 
reserved operand unless you have written a 
condition handler to change CHF $L_MCH_ 
SAVRO/R1. 


MTH-85 


MTHSHCOS 


MTH$HCOS—Cosine of Angle Expressed in Radians (H-Floating 
Value) 


The Cosine of Angle Expressed in Radians (H-Floating Value) routine returns the 
cosine of a given angle (in radians) as an H-floating value. 


Format 
MTH$HCOS h-cosine ,angle-in-radians 
JSB Entries 
MTH$HCOS_R5 
Returns 
None. 
Arguments 
h-cosine 
OpenVMS usage _ floating_point 
type H_fioating 
access write only 
mechanism by reference 


Cosine of the angle specified by angle-in-radians. The h-cosine argument is 
the address of an H-floating number that is this cosine. MTH$HCOS writes the 
address of the cosine into h-cosine. 


angle-in-radians 
OpenVMS usage _ floating_point 


type H_floating 
access read only 
mechanism by reference 


The angle in radians. The angle-in-radians argument is the address of a 
floating-point number. For MTH$HCOS, angle-in-radians specifies an H- 
floating number. 


Description 
See the MTH$xSINCOS routine for the algorithm used to compute the cosine. 


Condition Value Signaled 


SS$ ROPRAND Reserved operand. The MTH$HCOS procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH-86 


MTHSHCOSD 


MTHS$HCOSD—Cosine of Angle Expressed in Degrees (H-Floating 


Format 


JSB Entries 


Returns 


Arguments 


Description 


Value) 


The Cosine of Angle Expressed in Degrees (H-Floating Value) routine returns the 
cosine of a given angle (in degrees) as an H-floating value. 


MTH$HCOSD h-cosine ,angle-in-degrees 


MTH$HCOSD_R5 


None. 

h-cosine 

OpenVMS usage  floating_point 
type H_floating 
access write only 
mechanism by reference 


Cosine of the angle specified by angle-in-degrees. The h-cosine argument is 
the address of an H-floating number that is this cosine. MTH$HCOSD writes this 
cosine into h-cosine. 


angle-in-degrees 
OpenVMS usage  floating_point 


type H_fioating 
access read only 
mechanism by reference 


Angle (in degrees). The angle-in-degrees argument is the address of a floating- 
point number. For MTH$HCOSD, angle-in-degrees specifies an H-floating 
number. 


See the MTH$SINCOSD routine for the algorithm used to compute the cosine. 


Condition Value Signaled 


SS$_ROPRAND Reserved operand. The MTH$HCOSD procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH-—87 


MTHS$HCOSH 


MTH$HCOSH—Hyperbolic Cosine (H-Floating Value) 


Format 


Returns 


Arguments 


Description 


MTH-88 


The Hyperbolic Cosine (H-Floating Value) routine returns the hyperbolic cosine of 
the input value as an H-floating value. 


MTH$HCOSH _h-cosh ,floating-point-input-value 


None. 

h-cosh 

OpenVMS usage _ floating_point 
type H_floating 
access write only 
mechanism by reference 


Hyperbolic cosine of the input value specified by floating-point-input-value. 
The h-cosh argument is the address of an H-floating number that is this 
hyperbolic cosine. MTH$HCOSH writes the address of the hyperbolic cosine into 
h-cosh. 


floating-point-input-value 
OpenVMS usage _ floating_point 


type H_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of 
this input value. For MTH$HCOSH, floating-point-input-value specifies an 
H-floating number. 


Computation of the hyperbolic cosine depends on the magnitude of the input 
argument. The range of the function is partitioned using four data-type- 
dependent constants: a(z), b(z), and c(z). The subscript z indicates the data 

type. The constants depend on the number of exponent bits (e) and the number of 
fraction bits (f) associated with the data type (z). 


The values of e and f are as follows: 


MTHSHCOSH 


The values of the constants in terms of e and f are: 


Variable Value 

a(z) q-f/2 

b(z) (f + 1)/2 * In(2) 
c(z) 2¢-1 + In(2) 


Based on the above definitions, zCOSH(X) is computed as follows: 


Value of X 

x] < ale) 
a(z)<|X| < .25 
.25<|X| < b(z) 
b(z)<|X| < c(z) 
o(e)</X1 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_FLOOVEMAT 


Value Returned 


1 

Computed using a power series expansion in |X |? 
(2zEXP(|X|) + 1/zEXP(|X|))/2 

zEXP(|X|)/2 

Overflow occurs 


Reserved operand. The MTH$HCOSH procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in Math Library: the 
absolute value of floating-point-input-value is 
greater than about yyy; LIB$SIGNAL copies the 
reserved operand to the signal mechanism vector. 
The result is the reserved operand -0.0 unless a 
condition handler changes the signal mechanism 
vector. The value of yyy is 113856.523. 


MTH-89 


MTHSHEXP 


MTH$HEXP—Exponential (H-Floating Value) 


Format 


JSB Entries 


Returns 


Arguments 


Description 


MTH-90 


The Exponential (H-Floating Value) routine returns the exponential of the input 
value as an H-floating value. 


MTH$HEXP __h-exp ,floating-point-input-value 


MTH$HEXP_R6 


None. 

h-exp 

OpenVMS usage _floating_point 
type H_floating 
access write only 
mechanism _ by reference 


Exponential of the input value specified by floating-point-input-value. The 
h-exp argument is the address of an H-floating number that is this exponential. 
MTH$HEXP writes the address of the exponential into h-exp. 


floating-point-input-value 
OpenVMS usage  floating_point 


type H_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of a 
floating-point number. For MTH$HEXP, floating-point-input-value specifies an 
H-floating number. 


The exponential of x is computed as: 


Value of x Value Returned 
tz > c(z) Overflow occurs 
t< — ¢(z) 0 

\z < 2-(ft+)) 1 

Otherwise a¥ 49U QW 


where: Y = INTEGER(s « In2(Z)) V = FRAC(a * In2(E)) * 16 
U = INTEGER(V)/16 W = FRAC(V)/16 2” = polynomial approximation of 
degree 14 for z = H. 


See also the section on the hyperbolic cosine for definitions of f and c(z). 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_FLOOVEMAT 


MTH$_FLOUNDMAT 


MTHSHEXP 


Reserved operand. The MTH$xEXP routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in Math Library: 
floating-point-input-value is greater than 
yyy; LIB$SIGNAL copies the reserved operand 
to the signal mechanism vector. The result is 
the reserved operand -0.0 unless a condition 
handler changes the signal mechanism vector. 
The value of yyy is approximately 11355.830 for 
MTH$HEXP. 


Floating-point underflow in Math Library: 
floating-point-input-value is less than or 
equal to yyy and the caller (CALL or JSB) has 
set hardware floating-point underflow enable. 
The result is set to 0.0. If the caller has not 
enabled floating-point underflow (the default), a 
result of 0.0 is returned but no error is signaled. 
The value of yyy is approximately —11356.523 for 
MTH$HEXP. 


MTH-91 


MTHSHLOG 


MTH$HLOG—Natural Logarithm (H-Floating Value) 


The Natural Logarithm (H-Floating Value) routine returns the natural (base e) 
logarithm of the input argument as an H-floating value. 


Format 
MTH$HLOG _h-natlog ,floating-point-input-value 
JSB Entries 
MTH$HLOG_R8 
Returns 
None. 
Arguments 
h-natlog 
OpenVMS usage floating_point 
type H_floating 
access write only 
mechanism by reference 


Natural logarithm of floating-point-input-value. The h-natlog argument is 
the address of an H-floating number that is this natural logarithm. MTH$HLOG 
writes the address of this natural logarithm into h-natlog. 


floating-point-input-value 
OpenVMS usage _floating_point 


type H_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of a 
floating-point number that is this value. For MTH$HLOG, floating-point-input- 
value specifies an H-floating number. 


Description 
Computation of the natural logarithm routine is based on the following: 
1. In(X *Y) = In(X) + In(Y) 


2. In(1+X) = X— X2/2+ X23 /3 — X*/4... 
for [XI <1 


8. In(X) = In(A) +24 (V +V3/34V°/54+V°/7...) 
where V = (X — A)/(X + A), A> 0, 
and p(y) = 2#(1+y/3 + y7/5...) 


For z = 2" « f, where n is an integer and f is in the interval of 0.5 to 1, define 
the following quantities: 


If n>1, then N=n—-1land F = 2f 


If n<0O, then N=nand F = f 


MTH-92 


From (1) it follows that: 
4. In(X) = N « In(2) + In(F) 


MTHSHLOG 


Based on the previous relationships, zLOG is computed as follows: 


1. If|F-1)< 275, 


zLOG(X) = N *zLOG(2)+W+W «p(W), 


where W = F-1. 


2. Otherwise, 


zLOG(X) = N +zLOG(2) + zLOG(A) + V « p(V7), 
where V = (F — A)/(F + A) and A and zLOG(A) 
are obtained by table look up. 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_LOGZERNEG 


Reserved operand. The MTH$HLOG procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Logarithm of zero or negative value. Argument 
floating-point-input-value is less than or equal 
to 0.0. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_MCH_SAVRO/R1. The result 

is the floating-point reserved operand unless 

you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


MTH-93 


MTH$HLOG2 


MTH$S$HLOG2—Base 2 Logarithm (H-Floating Value) 


Format 


Returns 


Arguments 


Description 


The Base 2 Logarithm (H-Floating Value) routine returns the base 2 logarithm of 
the input value specified by floating-point-input-value as an H-floating value. 


MTH$HLOG2 _h-log2 ,floating-point-input-value 


None. 

h-log2 

OpenVMS usage _floating_point 
type H_floating 
access write only 
mechanism by reference 


Base 2 logarithm of floating-point-input-value. The h-log2 argument is the 
address of an H-floating number that is this base 2 logarithm. MTH$HLOG2 
writes the address of this logarithm into h-log2. 


floating-point-input-value 
OpenVMS usage _floating_point 


type H_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of 
a floating-point number that is this input value. For MTH$HLOG2, floating- 
point-input-value specifies an H-floating number. 


The base 2 logarithm function is computed as follows: 


zLOG2(X) = zLOG2(E) * zLOG(X) 


Condition Values Signaled 


MTH-94 


SS$ ROPRAND Reserved operand. The MTH$HLOG2 procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTHS$HLOG2 


MTH$ LOGZERNEG Logarithm of zero or negative value. Argument 
floating-point-input-value is less than or equal 
to 0.0. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_MCH_SAVRO/R1. The result 
is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


MTH-95 


MTHSHLOG10 


MTH$HLOG10—Common Logarithm (H-Floating Value) 


Format 


JSB Entries 


Returns 


Arguments 


Description 


MTH-—96 


The Common Logarithm (H-Floating Value) routine returns the common (base 10) 
logarithm of the input argument as an H-floating value. 


MTH$HLOG10_ h-log10 ,floating-point-input-value 


MTH$HLOG10_R8 


None. 

h-log10 

OpenVMS usage  floating_point 
type H_floating 
access write only 
mechanism by reference 


Common logarithm of the input value specified by floating-point-input-value. 
The h-log10 argument is the address of an H-floating number that is this 
common logarithm. MTH$HLOG10 writes the address of the common logarithm 
into h-log10. 


floating-point-input-value 
OpenVMS usage _ floating_point 


type H_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of a 
floating-point number. For MTH$HLOG10, floating-point-input-value specifies 
an H-floating number. 


The common logarithm function is computed as follows: 


zLOG10(X) = zLOG10(E) « zLOG(X) 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_LOGZERNEG 


MTHSHLOG10 


Reserved operand. The MTH$HLOG10 
procedure encountered a floating-point reserved 
operand due to incorrect user input. A floating- 
point reserved operand is a floating-point datum 
with a sign bit of 1 and a biased exponent of 0. 
Floating-point reserved operands are reserved for 
future use by Digital. 


Logarithm of zero or negative value. Argument 
floating-point-input-value is less than or equal 
to 0.0. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_MCH_SAVR0O/R1. The result 

is the floating-point reserved operand unless 

you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


AATH_A7 


MTHSHSIN 


MTH$HSIN—Sine of Angle Expressed in Radians (H-Floating Value) 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Sine of Angle Expressed in Radians (H-Floating Value) routine returns the 
sine of a given angle (in radians) as an H-floating value. 


MTH$HSIN _h-sine ,angle-in-radians 


MTH$HSIN_R5 

None. 

h-sine 

OpenVMS usage  floating_point 
type H_floating 
access write only 
mechanism by reference 


The sine of the angle specified by angle-in-radians. The h-sine argument is the 
address of an H-floating number that is this sine. MTH$HSIN writes the address 
of the sine into h-sine. 


angle-in-radians 
OpenVMS usage _floating_point 


type H_floating 
access read only 
mechanism by reference 


Angle (in radians). The angle-in-radians argument is the address of a floating- 
point number that is this angle. For MTH$HSIN, angle-in-radians specifies an 
H-floating number. 


See the MTH$SINCOS routine for the algorithm used to compute this sine. 


Condition Value Signaled 


hATH—QR 


SS$_ ROPRAND Reserved operand. The MTH$HSIN procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTHS$HSIND 


MTHSHSIND—Sine of Angle Expressed in Degrees (H-Floating Value) 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Sine of Angle Expressed in Degrees (H-Floating Value) routine returns the 
sine of a given angle (in degrees) as an H-floating value. 


MTH$HSIND h-sine ,angle-in-degrees 


MTHS$HSIND_R5 


None. 

h-sine 

OpenVMS usage _ floating_point 
type H_floating 
access write only 
mechanism by reference 


Sine of the angle specified by angle-in-degrees. The h-sine argument is the 
address of an H-floating number that is this sine. MTH$HSIND writes the 
address of the angle into h-sine. 


angle-in-degrees 
OpenVMS usage floating_point 


type H_floating 
access read only 
mechanism by reference 


Angle (in degrees). The angle-in-degrees argument is the address of a floating- 
point number that is this angle. For MTH$HSIND, angle-in-degrees specifies 
an H-floating number. 


See MTH$SINCOSD for the algorithm used to compute the sine. 


Condition Values Signaled 


SS$_ROPRAND Reserved operand. The MTH$HSIND procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


\ATH—QQ 


MTHSHSIND 


MTH$_FLOUNDMAT Floating-point underflow in Math Library. The 
absolute value of the input angle is less than 
180/x * 2~™ (where m = 16,384 for H-floating). 


MTH-100 


MTH$HSINH 


MTHSHSINH—Hyperbolic Sine (H-Floating Value) 


Format 


Returns 


Arguments 


Description 


The Hyperbolic Sine (H-Floating Value) routine returns the hyperbolic sine of the 
input value specified by floating-point-input-value as an H-floating value. 


MTH$HSINH _h-sinh ,floating-point-input-value 


None. 

h-sinh 

OpenVMS usage = floating_point 
type H_floating 
access write only 
mechanism by reference 


Hyperbolic sine of the input value specified by floating-point-input-value. The 
h-sinh argument is the address of an H-floating number that is this hyperbolic 
sine. MTH$HSINH writes the address of the hyperbolic sine into h-sinh. 


floating-point-input-value 
OpenVMS usage _floating_point 


type H_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of 
a floating-point number that is this value. For MTH$HSINH, floating-point- 
input-value specifies an H-floating number. 


Computation of the hyperbolic sine function depends on the magnitude of the 
input argument. The range of the function is partitioned using three data type 
dependent constants: a(z), b(z), and c(z). The subscript z indicates the data type. 
The constants depend on the number of exponent bits (e) and the number of 
fraction bits (f) associated with the data type (z). 


The values of e and f are as follows: 
e=15 


f= 113 
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The values of the constants in terms of e and f are: 


Variable Value 

a(z) o(- f/2) 

b(z) (f + 1)/2 « In(2) 
c(z) ge-1y In(2) 


Based on the above definitions, zSINH(X) is computed as follows: 


Value of X 
|X| < a(z) 
a(z)<|X| < 1.0 


1.0<|X| < b(z) 
b(z)<|X| < c(z) 
c(z)<|X| 


Condition Values Signaled 
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Value Returned 


ZOINH(X) is computed using a power series expansion in 


(zEX P(X) — zEX P(-—X))/2 
SIGN(X) « zEXP(|X|) /2 
Overflow occurs 


Reserved operand. The MTH$HSINH procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in Math Library: the 
absolute value of floating-point-input-value 

is greater than yyy. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVR0O/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF$L_MCH_SAVRO/R1. The value of 
yyy is approximately 11356.523. 
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MTHSHSQRT—Square Root (H-Floating Value) 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Square Root (H-Floating Value) routine returns the square root of the input 
value floating-point-input-value as an H-floating value. 


MTHS$HSQART _h-saqrt ,floating-point-input-value 


MTH$HSQRT_R8& 


None. 

h-sart 

OpenVMS usage floating_point 
type H_floating 
access write only 
mechanism by reference 


Square root of the input value specified by floating-point-input-value. The 
h-sqrt argument is the address of an H-floating number that is this square root. 
MTH$HSQRT writes the address of the square root into h-sqrt. 


floating-point-input-value 
OpenVMS usage _ floating_point 


type H_floating 
access read only 
mechanism by reference 


Input value. The floating-point-input-value argument is the address of 
a floating-point number that contains this input value. For MTH$HSQRT, 
floating-point-input-value specifies an H-floating number. 


The square root of X is computed as follows: 


If X < 0, an error is signaled. 

Let X =2% 4 F 

where: 

K is the exponential part of the floating-point data 
F is the fractional part of the floating-point data 


If K is even: 
X = 2(2*P) F 
zSQRT(X) = 2? «zSQRT(F), 
1/2<F < 1, where P = K/2 
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If K is odd: 
KX — 9(2*P+) y pH 9(24P+2) , (F/2), 
zSQRT(X) = 2+) « 2zSQRT(F/2), 
1/4<F/2 < 1/2, where p = (K-1)/2 

Let F' = A+ F +B, when K is even: 

A = 0.95F6198 (hex) 

B = 0.6BA5918 (hex) 

Let F! = Ax (F/2)+ B, when K is odd: 

A = 0.D418CCC (hex) 

B = 0.4C1E248 (hex) 

Let K’ = P, when K is even 

Let K’ = P+1, when K is odd 


Let Y[o] = 2% ' + F' be a straight line approximation within the given interval 
using coefficients A and B which minimize the absolute error at the midpoint and 
endpoint. 


Starting with Y[0], n Newton-Raphson iterations are performed: 


Y([n +1] =1/2*(Y|n] + X/Y[nl) 


where n = 5 for H-floating. 


Condition Values Signaled 


SS$_ROPRAND Reserved operand. The MTH$HSQRT procedure 


encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$_SQUROONEG Square root of negative number. Argument 
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floating-point-input-value is less than 0.0. 
LIB$SIGNAL copies the floating-point reserved 
operand to the mechanism argument vector 
CHF$L_MCH SAVRO/R1. The result is the 
floating-point reserved operand unless you have 
written a condition handler to change CHF$L_ 
MCH_SAVRO/R1. 


MTHSHTAN 


MTHSHTAN—Tangent of Angle Expressed in Radians (H-Floating 


Format 


JSB Entries 


Returns 


Arguments 


Description 


Value) 


The Tangent of Angle Expressed in Radians (H-Floating Value) routine returns 
the tangent of a given angle (in radians) as an H-floating value. 


MTH$HTAN _h-tan ,angle-in-radians 


MTHS$HTAN_R5 


None. 

h-tan 

OpenVMS usage  floating_point 
type H_floating 
access write only 
mechanism by reference 


Tangent of the angle specified by angle-in-radians. The h-tan argument is the 
address of an H-floating number that is this tangent. MTH$HTAN writes the 
address of the tangent into h-tan. 


angle-in-radians 
OpenVMS usage _ floating_point 


type H_floating 
access read only 
mechanism by reference 


The input angle (in radians). The angle-in-radians argument is the address of 
a floating-point number that is this angle. For MTH$HTAN, angle-in-radians 
specifies an H-floating number. 


When the input argument is expressed in radians, the tangent function is 
computed as follows: 


1. If |X| < 2-f/2), then zTAN(X) = X (see the section on MTH$zCOSH for the 
definition of /) 


2. Otherwise, call MTH$zSINCOS to obtain zSIN(X) and zCOS(X); then 
a. If zCOS(X) =0, signal overflow 
b. Otherwise, zTAN(X) = zSIN(X)/zCOS(X) 
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Condition Values Signaled 
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SS$_ROPRAND 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$HTAN procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in math library. 


MTHS$HTAND 


MTHSHTAND—Tangent of Angle Expressed in Degrees (H-Floating 


Format 


JSB Entries 


Returns 


Arguments 


Description 


Value) 


The Tangent of Angle Expressed in Degrees (H-Floating Value) routine returns 
the tangent of a given angle (in degrees) as an H-floating value. 


MTH$HTAND _ h-tan ,angle-in-degrees 


MTH$HTAND_R5 


None. 

h-tan 

OpenVMS usage _ floating_point 
type H_floating 
access write only 
mechanism by reference 


Tangent of the angle specified by angle-in-degrees. The h-tan argument is the 
address of an H-floating number that is this tangent. MTH$HTAND writes the 
address of the tangent into h-tan. 


angle-in-degrees 
OpenVMS usage  floating_point 


type | H_floating 
access read only 
mechanism by reference 


The input angle (in degrees). The angle-in-degrees argument is the address of a 
floating-point number which is this angle. For MTH$HTAND, angle-in-degrees 
specifies an H-floating number. 


When the input argument is expressed in degrees, the tangent function is 
computed as follows: 


1. If |X| < (180/7) » 2°-2/e-D) and underflow signaling is enabled, underflow is 
signaled (see the section on MTH$zCOSH for the definition of e). 


2. Otherwise, if |X| < (180/7) « 2‘-f/2), then zTAN D(X) = (1/180) » X. See the 
description of MTH$zCOSH for the definition of f. 


3. Otherwise, call MTH$zSINCOSD to obtain zSIND(X) and zCOSD(X). 
a. Then, if zCOSD(X) = 0, signal overflow 
b. Else, zTAN D(X) = zSIND(X)/zCOS D(X) 
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Condition Values Signaled 
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SS$_ROPRAND 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$HTAND procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in math library. 


MTHSHTANH 


MTHSHTANH—Compute the Hyperbolic Tangent (H-Floating Value) 


Format 


Returns 


Arguments 


Description 


The Compute the Hyperbolic Tangent (H-Floating Value) routine returns the 
hyperbolic tangent of the input value as an H-floating value. 


MTH$HTANH _h-tanh ,floating-point-input-value 


None. 

h-tanh 

OpenVMS usage _ floating_point 
type H_floating 
access write only 
mechanism by reference 


Hyperbolic tangent of the value specified by floating-point-input-value. The 
h-tanh argument is the address of a H-floating number that is this hyperbolic 
tangent. MTH$HTANH writes the address of the hyperbolic tangent into h-tanh. 


floating-point-input-value 
OpenVMS usage _ floating_point 


type H_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address 
of a floating-point number that contains this input value. For MTH$HTANH, 
floating-point-input-value specifies an H-floating number. 


For MTH$HTANH, the hyperbolic tangent of X is computed using a value of 56 
for g and a value of 40 for h. The hyperbolic tangent of X is computed as follows: 


Value of x Hyperbolic Tangent Returned 

|X|<279 x 

2-9 < |X |<0.25 zSINH(X)/zCOS H(X) | 

0.25 < |X| <h (2EX P(2* X) —1)/(zEXP(2 * X) +1) 
h<|X| sign(X) *1 
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Condition Value Signaled 
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SS$_ROPRAND 


Reserved operand. The MTH$HTANH procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$xIMAG 


MTH$xIMAG—Imaginary Part of a Complex Number 


The Imaginary Part of a Complex Number routine returns the imaginary part of 
a complex number. 


Format 
MTH$AIMAG complex-number 
MTH$DIMAG complex-number 
MTH$GIMAG complex-number 


Each of the above three formats corresponds to one of the three floating-point 
complex types. 


Returns 
OpenVMS usage  floating_point 
type F’ floating, D_floating, G_floating 
access write only 
mechanism by value 


Imaginary part of the input complex-number. MTH$AIMAG returns an F- 
floating number. MTH$DIMAG returns a D-floating number. MTH$GIMAG 
returns a G-floating number. 


ARGUMENT 


complex-number 
OpenVMS usage complex_number 


type F_floating complex, D_floating complex, G_floating complex 
access read only 
mechanism by reference 


The input complex number. The complex-number argument is the address 

of this floating-point complex number. For MTH$AIMAG, complex-number 
specifies an F-floating number. For MTH$DIMAG, complex-number specifies a 
D-floating number. For MTH$GIMAG, complex-number specifies a G-floating 
number. 


Condition Value Signaled 


SS$_ROPRAND Reserved operand. The MTH$xIMAG routine 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 
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Example 


MTH—119 


+ 


This FORTRAN example forms the imaginary part of 
a G-floating complex number using MTHSGIMAG 

and the FORTRAN random number generator 

RAN. 


Declare Z as a complex value and MTHSGIMAG as 
a REAL*8 value. MTHSGIMAG will return the imaginary 
part of Z: 2% NEW = MTHSGIMAG(Z). 


MAA A ARANIRANIUANA 


COMPLEX*16 Z 
COMPLEX*16 DCMPLX 
REAL*8 R,1I,MTHSGIMAG 
INTEGER M 

M = 1234567 


C Generate a random complex number with the 
C FORTRAN generic CMPLX. 


Cz 
R = RAN(M) 
I = RAN(M) 
Z = DCMPLX(R,I) 
C+ 
C Z is a complex number (r,i) with real part "r" and 
C imaginary part "i". 
C- 


TYPE *, ' The complex number z is’,z 
TYPE *, ' It has imaginary part’ ,MTHSGIMAG(Z) 
END 


This FORTRAN example demonstrates a procedure call to MTH$GIMAG. 
Because this example uses G-floating numbers, it must be compiled with the 
statement “FORTRAN/G filename”. 


The output generated by this program is as follows: 


The complex number z is (0.8535407185554504,0.2043401598930359) 
It has imaginary part 0.2043401598930359 


MTH$xLOG 


MTH$xLOG—Natural Logarithm 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Natural Logarithm routine returns the natural (base e) logarithm of the 
input argument. 


MTH$ALOG _ floating-point-input-value 
MTH$DLOG _ floating-point-input-value 
MTH$GLOG _ floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


MTH$ALOG_R5 
MTH$DLOG_R8 
MTH$GLOG_R8 
Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F_floating, D_floating, G_floating 
access write only 
mechanism by value 


The natural logarithm of floating-point-input-value. MTH$ALOG returns 
an F-floating number. MTH$DLOG returns a D-floating number. MTH$GLOG 
returns a G-floating number. 


floating-point-input-value 
OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of a 
floating-point number that is this value. For MTH$ALOG, floating-point-input- 
value specifies an F-floating number. For MTH$DLOG, floating-point-input- 
value specifies a D-floating number. For MTH$GLOG, floating-point-input- 
value specifies a G-floating number. 


Computation of the natural logarithm routine is based on the following: 
1. In(X#Y) =In(X)4+W(Y) 


2. In(i+ X) =X — X*/2+X3/3— X*/4... 
for |X| <1 
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3. In(X) = In(A) +24 (V 4+V3/34+V°/54+V"/7..,) 
= In(A) + V *p(V7), where V = (X — A)/(X + A), 
A> 0, and p(y) = 2* (14+ y/3 + 7/5...) 
For xz = 2" « f, where n is an integer and f is in the interval of 0.5 to 1, define 
the following quantities: 


If n>1, then N=n-1land F=2f 


If n<0, then N=nand F=f 
From (1) above it follows that: 
4. In(X) = N *In(2) +In(F) 
Based on the above relationships, zLOG is computed as follows: 


1. If |F—1)< 27°, 2LOG(X) = N+zLOG(2)+W+W «p(W), 
where W = F-1. 


2. Otherwise, zLOG(X) = N + zLOG(2) + zLOG(A) + V + p(V7), 
where V = (F — A)/(F + A) and A and zLOG(A) 
are obtained by table look up. 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HLOG. 


Condition Values Signaled 


SS$_ROPRAND Reserved operand. The MTH$xLOG procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$_LOGZERNEG Logarithm of zero or negative value. Argument 
floating-point-input-value is less than or equal 
to 0.0. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF$L_MCH_ SAVRO/R1. The result 
is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 
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MTH$xLOG2—Base 2 Logarithm 


Format 


Returns 


Arguments 


Description 


The Base 2 Logarithm routine returns the base 2 logarithm of the input value 
specified by floating-point-input-value. 


MTH$ALOG2 | floating-point-input-value 
MTH$DLOG2 __ floating-point-input-value 
MTH$GLOG2 | floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F_floating, D_floating, G_floating 
access write only 
mechanism by value 


The base 2 logarithm of floating-point-input-value. MTH$ALOG2 returns an 
F-floating number. MTH$DLOG2 returns a D-floating number. MTH$GLOG2 
returns a G-floating number. - 


floating-point-input-value 
OpenVMS usage _ floating point 


type F_floating, D_floating, G_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of 
a floating-point number that is this input value. For MTH$ALOG2, floating- 
point-input-value specifies an F-floating number. For MTH$DLOG2, floating- 
point-input-value specifies a D-floating number. For MTH$GLOG2, floating- 
point-input-value specifies a G-floating number. 


The base 2 logarithm function is computed as follows: 


zLOG2(X) = zLOG2(E) « zLOG(X) 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HLOG2. 
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Condition Values Signaled 
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SS$_ROPRAND 


MTH$_LOGZERNEG 


Reserved operand. The MTH$xLOG2 procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. | 


Logarithm of zero or negative value. Argument 
floating-point-input-value is less than or equal 
to 0.0. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 
vector CHF $L_MCH_SAVRO/R1. The result 

is the floating-point reserved operand unless 

you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


MTH$xLOG10 


MTH$xLOG10—Common Logarithm 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Common Logarithm routine returns the common (base 10) logarithm of the 
input argument. 


MTH$ALOG10 _ floating-point-input-value 
MTH$DLOG10 _ floating-point-input-value 
MTH$GLOG10 _ floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


MTH$ALOG10_R5 
MTH$DLOG10_R8 
MTH$GLOG10_R8 
Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F floating, D_floating, G_floating 
access write only | 
mechanism by value 


The common logarithm of floating-point-input-value. MTH$ALOG10 
returns an F-floating number. MTH$DLOG10 returns a D-floating number. 


MTH$GLOG10 returns a G-floating number. 


floating-point-input-value 
OpenVMS usage  floating_point 


type F_ floating, D_floating, G_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of a 
floating-point number. For MTH$ALOG10, floating-point-input-value specifies 
an F-floating number. For MTH$DLOG10, floating-point-input-value specifies 
a D-floating number. For MTH$GLOG10, floating-point-input-value specifies a 
G-floating number. 


The common logarithm function is computed as follows: 


zLOG10(X) = zLOG10(E) « zLOG(X) 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HLOG10. 
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Condition Values Signaled 


MTH—118 


SS$_ROPRAND 


MTH$_LOGZERNEG 


Reserved operand. The MTH$xLOG10 procedure 


encountered a floating-point reserved operand 


due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Logarithm of zero or negative value. Argument 
floating-point-input-value is less than or equal 
to 0.0. LIB$SIGNAL copies the floating-point 


reserved operand to the mechanism argument 


vector CHF$L_MCH_SAVRO/R1. The result 

is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$L_MCH_SAVRO/R1. 


MTHSRANDOM > 


MTHSRANDOM—Random Number Generator, Uniformly Distributed 


The Random Number Generator, Uniformly Distributed routine is a general 
random number generator. 


Format 
MTH$RANDOM seed 
Returns 
OpenVMS usage _floating_point 
type F_ floating 
access write only 
mechanism by value 
MTH$RANDOM returns an F-floating random number. 
ARGUMENT 
seed 
OpenVMS usage longword_unsigned 
type longword (unsigned) 
access modify 
mechanism by reference 
The integer seed, a 32-bit number whose high-order 24 bits are converted by 
MTH$RANDOM to an F-floating random number. The seed argument is the 
address of an unsigned longword that contains this mnteeer seed. The seed is 
modified by each call to MTH$RANDOM. 
Description 


This routine must be called again to obtain the next pseudorandom number. The 
seed is updated automatically. 


The result is a floating-point number that is uniformly distributed between 0.0 
inclusively and 1.0 exclusively. 


There are no restrictions on the seed, although it should be initialized to 
different values on separate runs in order to obtain different random sequences. 
MTH$RANDOM uses the following method to update the seed passed as the 
argument: 

SEED = (69069 * SEED + 1)(modulo2°*) 


Condition Value Signaled 


SS$_ROPRAND Reserved operand. The MTH$RANDOM 
procedure encountered a floating-point reserved 
operand due to incorrect user input. A floating- 
point reserved operand is a floating-point datum 
with a sign bit of 1 and a biased exponent of 0. 
Floating-point reserved operands are reserved for 
future use by Digital. 
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Example 
RAND: PROCEDURE OPTIONS (MAIN); 
DECLARE FORSSECNDS ENTRY (FLOAT BINARY (24)) 
RETURNS (FLOAT BINARY (24)); 
DECLARE MTHSRANDOM ENTRY (FIXED BINARY (31)) 
RETURNS (FLOAT BINARY (24)); 
DECLARE TIME FLOAT BINARY (24); 
DECLARE SEED FIXED BINARY (31); 
DECLARE I FIXED BINARY (7); 
DECLARE RESULT FIXED DECIMAL (2); 
/* Get floating random time value */ 
TIME = FORSSECNDS (0E0); 
/* Convert to fixed * / 
SEED = TIME; 
/* Generate 100 random numbers between 1 and 10 */ 
DO I = 1 TO 100; 
RESULT = 1 + FIXED ( (10E0 * MTHSRANDOM (SEED) ),31 ); 
PUT LIST (RESULT) ; 
END; 
END RAND; 
This PL/I program demonstrates the use of MTH$RANDOM. The value returned 
by FOR$SECNDS is used as the seed for the random-number generator to ensure 
a different sequence each time the program is run. The random value returned is 
scaled so as to represent values between 1 and 10. 
Because this program generates random numbers, the output generated will be 
different each time the program is executed. One example of the outut generated 
by this program is as follows: 
7 4 6 5 9 10 5 5 3 8 8 1 3 1 3 2 
4 4 2 4 4 8 3 8 9 1 7 1 8 6 9 10 
1 10 10 6 7 3 2 Z 1 2 6 6 3 9 5 8 
6 2 3 6 10 8 5 5 4 2 8 5 9 6 4 2 
8 5 4 9 8 7 6 6 8 10 9 5 9 4 5 7 
1 Z 2 3 6 5 2 3 4 4 8 9 2 8 5 5 
3 8 1 5 
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MTH$xREAL—Real Part of a Complex Number 


Format 


Returns 


ARGUMENT 


The Real Part of a Complex Number routine returns the real part of a complex 
number. 


MTHS$REAL complex-number 
MTH$DREAL complex-number 
MTH$GREAL complex-number 


Each of the above three formats accepts one of the three floating-point complex 
types as input. 


OpenVMS usage _ floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


Real part of the complex number. MTH$REAL returns an F-floating number. 
MTH$DREAL returns a D-floating number. MTH$GREAL returns a G-floating 
number. 


complex-number 
OpenVMS usage complex_number 


type F floating complex, D_floating complex, G_floating complex 
access read only 
mechanism by reference 


The complex number whose real part is returned by MTH$REAL. The 
complex-number argument is the address of this floating-point complex 
number. For MTH$REAL, complex-number is an F-floating complex number. 
For MTH$DREAL, complex-number is a D-floating complex number. For 
MTH$GREAL, complex-number is a G-floating complex number. 


Condition Value Signaled 


SS$_ROPRAND Reserved operand. The MTH$xREAL procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 
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MTHS$xREAL 


Example 
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C+ 
C This FORTRAN example forms the real 
C part of an F-floating complex number using 
C MTHSREAL and the FORTRAN random number 
C generator RAN. 
C 
C Declare Z as a complex value and MTHSREAL as a 
C REAL*4 value. MTHSREAL will return the real 
C part of Z: 4% NEW = MTHSREAL(Z). 
C- 
COMPLEX 2Z 
COMPLEX CMPLX 
REAL*4 MTHSREAL 
INTEGER M 
M = 1234567 
Ct 


C Generate a random complex number with the FORTRAN 
C generic CMPLX. 


La | 
iT 


CMPLX (RAN(M) ,RAN(M) ) 


Cc Z is a complex number (r,i) with real part "r" and imaginary 
C part "i". 


TYPE *, '’ The complex number z is’,z 
TYPE *, '’ It has real part’ ,MTHSREAL(Z) 
END 


This FORTRAN example demonstrates the use of MTH$REAL. The output of this 
program is as follows: 


The complex number z is (0.8535407,0.2043402) 
It has real part 0.8535407 
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MTH$xSIN—Sine of Angle Expressed in Radians 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Sine of Angle Expressed in Radians routine returns the sine of a given angle 
(in radians). 


MTH$SIN  angle-in-radians 
MTH$DSIN = angle-in-radians 
MTH$GSIN_ angle-in-radians 


Each of the above formats accepts one of the floating-point types as input. 


MTH$SIN_R4 

MTH$DSIN_R7 

MTH$GSIN_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage _ floating_point 


type F_floating, D_floating, G_floating 
access write only 
mechanism by value 


Sine of the angle specified by angle-in-radians. MTH$SIN returns an F- 
floating number. MTH$DSIN returns a D-floating number. MTH$GSIN returns a 
G-floating number. 


angle-in-radians 
OpenVMS usage _ floating_point 


type F’_floating, D_floating, G_floating 
access read only 
mechanism by reference 


Angle (in radians). The angle-in-radians argument is the address of a floating- 
point number that is this angle. For MTH$SIN, angle-in-radians specifies an 
F-floating number. For MTH$DSIN, angle-in-radians specifies a D-floating 
number. For MTH$GSIN, angle-in-radians specifies a G-floating number. 


See the MTH$SINCOS routine for the algorithm used to compute this sine. 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HSIN. 
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MTH$xSIN 


Condition Value Signaled 
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SS$_ROPRAND 


Reserved operand. The MTH$xSIN procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$xSINCOS 


MTH$xSINCOS—Sine and Cosine of Angle Expressed in Radians 


Format 


JSB Entries 


Returns 


Arguments 


The Sine and Cosine of Angle Expressed in Radians routine returns the sine and 
cosine of a given angle (in radians). 


MTH$SINCOS _angle-in-radians ,sine ,cosine 

MTH$DSINCOS _ angle-in-radians ,sine ,cosine 
MTH$GSINCOS _§angle-in-radians ,sine ,cosine 
MTH$HSINCOS =§angle-in-radians ,sine ,cosine 


Each of the above four formats accepts one of the four floating-point types as 
input. 


MTH$SINCOS_R5 

MTH$DSINCOS_R7 
MTH$GSINCOS_R7 
MTH$HSINCOS_R7 


Each of the above four JSB entries accepts one of the four floating-point types as 
input. 


MTH$SINCOS, MTH$DSINCOS, MTH$GSINCOS, and MTH$HSINCOS return 
the sine and cosine of the input angle by reference in the sine and cosine 
arguments. 


angle-in-radians 
OpenVMS usage  floating_point 


type F_floating, D_floating, G_floating, H_floating 
access read only 
mechanism by reference 


Angle (in radians) whose sine and cosine are to be returned. The angle-in- 
radians argument is the address of a floating-point number that is this 

angle. For MTH$SINCOS, angle-in-radians is an F-floating number. For 
MTH$DSINCOS, angle-in-radians is a D-floating number. For MTH$GSINCOS, 
angle-in-radians is a G-floating number. For MTH$HSINCOS, angle-in- 
radians is an H-floating number. 


sine 

OpenVMS usage  floating_point 

type EF’ floating, D_floating, G_floating, H_floating 
access write only 

mechanism by reference 
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MTH$xSINCOS 


Description 


MTH-126 


Sine of the angle specified by angle-in-radians. The sine argument is the 
address of a floating-point number. MTH$SINCOS writes an F-floating 
number into sine. MTH$DSINCOS writes a D-floating number into sine. 
MTH$GSINCOS writes a G-floating number into sine. MTH$HSINCOS writes 
an H-floating number into sine. 


cosine 

OpenVMS usage floating point 

type F_floating, D_floating, G_floating, H_floating 
access | write only 

mechanism by reference 


Cosine of the angle specified by angle-in-radians. The cosine argument is 

the address of a floating-point number. MTH$SINCOS writes an F-floating 
number into cosine. MTH$DSINCOS writes a D-floating number into cosine. 
MTH$GSINCOS writes a G-floating number into cosine. MTH$HSINCOS writes 
an H-floating number into cosine. 


All routines with JSB entry points accept a single argument in RO:Rm, where m, 
which is defined below, is dependent on the data type. 


Data Type m 
F floating 0 
D_floating 1 
G_floating 1 
H_floating 3 


In general, Run-Time Library routines with JSB entry points return one value 
in RO:Rm. The MTH$SINCOS routine returns two values, however. The sine of 
angle-in-radians is returned in RO:Rm and the cosine of angle-in-radians is | 
returned in (R<m+1>:R<2*m+1>). 


In radians, the computation of zSIN(X) and zCOS(X) is based on the following 
polynomial expansions: 


sin(X) = X — X3/(3!) + X°/(5!) — X7/(7))... 
= X + X « P(X*), where 
P(y) = y/(3!) + y?/(5!) + y?/(7))... 


cos(X) = 1— X?/(2!) + «*/(4!) — X®/(6))... 
= Q(X?), where 
Q(y) = (1 — y/(2!) + y?/(4!) + 9°/(6!)...) 
1. If |X| <2 F/), 
then zSIN(X) = X and zCOS(X) = 1 
(see the section on MTH$zCOSH for 
the definition of f) 


2. If2-f/%<|X| < 2/4, 
then zSIN(X) = X + P(X?) 
and zCOS(X) = Q(X?) 


3. If/4<|X| and X > 0, 


a. Let J = INT(X/(z/4)) 
and J = Jmodulo 8 


b. 


If J is even, let Y = X — J « (1/4) 


otherwise, let Y = (J +1) « (7/4) — X 
With the above definitions, the following table relates zSIN(X) and 


zCOS(X) to zSIN(Y) and zCOS(Y): 


Value of / ZSIN(X) zCOS(X) 
0 ZOIN(Y) zZCOS(Y) 
1 zCOS(Y) zSIN(Y) 
2 zCOS(Y) -ZSIN(Y) 
3 ZOIN(Y) -zCOS(Y) 
4 -ZSIN(Y) -zCOS(Y) 
5 -zCOS(Y) -ZSIN(Y) 
6 -zCOS(Y) ZOIN(Y) 
7 -ZSIN(Y) zCOS(Y) 


zSIN(Y) and zCOS(Y) are computed as follows: 


MTH$xSINCOS 


2zSIN(Y) =Y + P(Y?), 
and zCOS(Y) = Q(Y?) 
4. Ifm/4<|X| and X < 0, 
then zSIN(X) = —zSIN(|X)) 
and zCOS(X) = zCOS({|X}) 


Condition Value Returned 


SS$ ROPRAND Reserved operand. The MTH$xSINCOS 


procedure encountered a floating-point reserved 
operand due to incorrect user input. A floating- 
point reserved operand is a floating-point datum 
with a sign bit of 1 and a biased exponent of 0. 
Floating-point reserved operands are reserved for 
future use by Digital. 
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MTH$xSINCOSD 


MTH$xSINCOSD—Sine and Cosine of Angle Expressed in Degrees 


Format 


JSB Entries 


Returns 


Arguments 
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The Sine and Cosine of Angle Expressed in Degrees routine returns the sine and 
cosine of a given angle (in degrees). 


MTH$SINCOSD angle-in-degrees ,sine ,cosine 

MTH$DSINCOSD _angle-in-degrees ,sine ,cosine 
MTH$GSINCOSD angle-in-degrees ,sine ,cosine 
MTHS$HSINCOSD =angle-in-degrees ,sine ,cosine 


Each of the above four formats accepts one of the four floating-point types as 
input. 


MTH$SINCOSD_R5 

MTHS$DSINCOSD_R7 
MTH$GSINCOSD_R7 
MTH$HSINCOSD_R7 


Each of the above four JSB entries accepts one of the four floating-point types as 
input. 


MTH$SINCOSD, MTH$DSINCOSD, MTH$GSINCOSD, and MTH$HSINCOSD 
return the sine and cosine of the input angle by reference in the sine and cosine 
arguments. 


angle-in-degrees 
OpenVMS usage  floating_point 


type F floating, D_floating, G_floating, H_floating 
access read only | 
mechanism by reference 


Angle (in degrees) whose sine and cosine are returned by MTH$xSINCOSD. 
The angle-in-degrees argument is the address of a floating-point number 
that is this angle. For MTH$SINCOSD, angle-in-degrees is an F-floating 
number. For MTH$DSINCOSD, angle-in-degrees is a D-floating number. 
For MTH$GSINCOSD, angle-in-degrees is a G-floating number. For 
MTH$HSINCOSD, angle-in-degrees is an H-floating number. 


sine 

OpenVMS usage _ floating_point 

type F_floating, D_floating, G_floating, H_floating 
access write only 

mechanism by reference 


Sine of the angle specified by angle-in-degrees. The sine argument is the 
address of a floating-point number. MTH$SINCOSD writes an F-floating 


Description 


MTH$xSINCOSD 


number into sine. MTH$DSINCOSD writes a D-floating number into sine. 
MTH$GSINCOSD writes a G-floating number into sine. MTH$HSINCOSD 
writes an H-floating number into sine. 


cosine 

OpenVMS usage  floating_point 

type F floating, D_floating, G_floating, H_floating 
access write only 

mechanism by reference 


Cosine of the angle specified by angle-in-degrees. The cosine argument is 
the address of a floating-point number. MTH$SINCOSD writes an F-floating 
number into cosine. MTH$DSINCOSD writes a D-floating number into cosine. 
MTH$GSINCOSD writes a G-floating number into cosine. MTH$HSINCOSD 
writes an H-floating number into cosine. 


All routines with JSB entry points accept a single argument in RO:Rm, where m, 
which is defined below, is dependent on the data type. 


Data Type m 
F_floating 0 
D_floating 1 
G_floating 1 
H_floating 3 


In general, Run-Time Library routines with JSB entry points return one value in 
RO:Rm. The MTH$SINCOSD routine returns two values, however. The sine of 
angle-in-degrees is returned in RO:Rm and the cosine of angle-in-degrees is 
returned in (R<m+1>:R<2*m+1>). 


In degrees, the computation of zSIND(X) and zCOSD(X) is based on the following 
polynomial expansions: 


SIND(X) = (C+ X) —(C*« X)?/(3!)+ 
(C x X)?/(5!) —(C« X)"/(7)... 
= X/2°+ X + P(X”), where 
Ply) = —y/(3!) + y*/(5!) — y?/(7!)... 


COS D(X) =1— (C « X)7/(2!)+ 
(C « X)*/(4!) — (C « X)§/(6!)... 
= Q(X”), where 
Q(y) = 1- y/(2!) + y?/(4!) — y3/())... 
and C = 7/180 


1. If |X| < (180/z) * 2-2°~" and underflow signaling is enabled, 
underflow is signaled for zSIND(X) and zSINCOSD(X). 
See MTH$zCOSH for the definition of e. 


otherwise: 


2. If |X| < (180/m) « 2°-F/2), 
then zSIN D(X) = (1/180) + X and zCOS D(X) = 1. 
(See MTH$zCOSH for the definition of f.) 
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MTH$xSINCOSD 


3. If (180/) #2-4/2) < |KI < 45 
then zSIN D(X) = X/2° + P(X?) 
and zCOS D(X) = Q(X”) 


4. If45<|X| and X > 0, 


a. Let J = INT(X/(45))and 


f= J meadulo 8 


b. IfJ is even, let Y = X — J x 45; 
otherwise, let Y = (J + 1) *45— X. 
With the above definitions, the following table relates 
ZSIND(X) and zCOSD(X) to zSIND(Y) and zCOSDCY): 


Value of / 


NOP ON & © 


ZSIND(X) zCOSD(X) 
ZSIND(Y) zCOSD(Y) 
zCOSD(Y) zSIND(Y) 
zCOSD(Y) -zSIND(Y) 
zSIND(Y) -zCOSD(Y) 
-ZSIND(Y) -zCOSD(Y) 
-zCOSD(Y) -zSIND(Y) 
-zCOSD(Y) zSIND(Y) 
-zSIND(Y) ~ zCOSD(Y) 


c. zSIND(Y) and zCOSD(Y) are computed as follows: 
zSIND(Y) = Y/2° + P(y?) 


zCOSD(Y) = Q(Y?) 
d. If45<|X| and X <0, 


then zSIN D(X) = -zSIND(|X)) 
and zCOS D(X) = zCOsD(|X)) 


Condition Values Signaled 
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SS$_ROPRAND 


MTH$_FLOUNDMAT 


Reserved operand. The MTH$xSINCOSD 
procedure encountered a floating-point reserved 
operand due to incorrect user input. A floating- 
point reserved operand is a floating-point datum 
with a sign bit of 1 and a biased exponent of 0. 
Floating-point reserved operands are reserved for 
future use by Digital. 


Floating-point underflow in math library. The 
absolute value of the input angle is less than 
180/a + 2-™ (where m = 128 for F-floating and 
D-floating, 1,024 for G-floating, and 16,384 for 
H-floating). 


MTH$xSIND 


MTH$xSIND—Sine of Angle Expressed in Degrees 


Format 


JSB Entries 


Returns 


Arguments 


Description 


The Sine of Angle Expressed in Degrees routine returns the sine of a given angle 
(in degrees). 


MTH$SIND _angle-in-degrees 
MTH$DSIND _ angle-in-degrees 
MTH$GSIND _angle-in-degrees 


Each of the above formats accepts one of the floating-point types as input. 


MTH$SIND_R4 

MTH$DSIND_R7 

MTH$GSIND_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type F_floating, D_floating, G_floating 
access write only 
mechanism by value 


The sine of the angle. MTH$SIND returns an F-floating number. MTH$DSIND 
returns a D-floating number. MTH$GSIND returns a G-floating number. 


angle-in-degrees 
OpenVMS usage floating_point 


type F_floating, D_floating, G_floating 
access read only 
mechanism by reference 


Angle (in degrees). The angle-in-degrees argument is the address of a floating- 
point number that is this angle. For MTH$SIND, angle-in-degrees specifies an 
F-floating number. For MTH$DSIND, angle-in-degrees specifies a D-floating 


number. For MTH$GSIND, angle-in-degrees specifies a G-floating number. 


See MTH$SINCOSD for the algorithm that is used to compute the sine. 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HSIND. 
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MTH$xSIND 


Condition Values Signaled 


MTH-132 


SS$_ROPRAND 


MTH$_FLOUNDMAT 


Reserved operand. The MTH$SIND procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point underflow in math library. The 
absolute value of the input angle is less than 
180/x * 2-™ (where m = 128 for F-floating and 
D-floating, and 1,024 for G-floating). 


MTH$xSINH 


MTH$xSINH—Hyperbolic Sine 


Format 


Returns 


Arguments 


Description 


The Hyperbolic Sine routine returns the hyperbolic sine of the input value 
specified by floating-point-input-value. 


MTH$SINH _ floating-point-input-value 
MTH$DSINH _ floating-point-input-value 
MTH$GSINH _ floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


OpenVMS usage floating_point 


type F_floating, D_floating, G_floating 
access write only 
mechanism by value 


The hyperbolic sine of floating-point-input-value. MTH$SINH returns an 
F-floating number. MTH$DSINH returns a D-floating number. MTH$GSINH 
returns a G-floating number. 


floating-point-input-value 
OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access read only 
mechanism by reference 


The input value. The floating-point-input-value argument is the address of a 
floating-point number that is this value. For MTH$SINH, floating-point-input- 
value specifies an F-floating number. For MTH$DSINH, floating-point-input- 
value specifies a D-floating number. For MTH$GSINH, floating-point-input- 
value specifies a G-floating number. 


Computation of the hyperbolic sine function depends on the magnitude of the 
input argument. The range of the function is partitioned using four data type 
dependent constants: a(z), b(z), and c(z). The subscript z indicates the data type. 
The constants depend on the number of exponent bits (e) and the number of 
fraction bits (f) associated with the data type (2). 
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MTH$xSINH 


The values of e and f are: 


8 
11 


qc © | N 


f 


24 
56 
53 


The values of the constants in terms of e and f are: 


Variable Value 
a(z) g(-f/2) 
b(z) CEILINGI(f + 1)/2 * In(2)] 


c(z) (2(e-D « In(2)) 


Based on the above definitions, zSINH(X) is computed as follows: 


Value of X 


IX | < a(z) 
a(z)< IXI <1.0 


1.0< I|XI <b(z) 
b(z) < I XI <c(z) 
e(z) < |X] 


Value Returned 


xX 


zSINH(X) is computed using a 
power series expansion in |X|? 


(2zEX P(X) — zEXP(-X))/2 
SIGN (X) * zEXP(|X|)/2 
Overflow occurs 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HSINH. 


Condition Values Signaled 
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SS$_ROPRAND 


Reserved operand. The MTH$xSINH procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$xSINH 


MTH$_ FLOOVEMAT Floating-point overflow in Math Library: the 
absolute value of floating-point-input-value 
is greater than yyy. LIB$SIGNAL copies the 
floating-point reserved operand to the mechanism 
argument vector CHF$L_MCH_SAVRO/R1. The 
result is the floating-point reserved operand 
unless you have written a condition handler to 
change CHF$L_MCH_SAVRO/R1. 


The values of yyy are approximately: 


MTH$SINH—88.722 
MTH$DSINH—88.722 
MTH$GSINH—709.782 


MTH—135 


MTH$xSQRT 


MTH$xSQRT—Square Root 


Format 


JSB Entries 


Returns 


Arguments 


Description 
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The Square Root routine returns the square root of the input value floating- 
point-input-value. 


MTH$SQRT _ floating-point-input-value 
MTH$DSQRT _ floating-point-input-value 
MTH$GSQRT _ floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


MTH$SQRT_R3 

MTH$DSQRT_R5 

MTH$GSQRT_R5 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


The square root of floating-point-input-value. MTH$SQRT returns an F- 
floating number. MTH$DSQRT returns a D-floating number. MTH$GSQRT 
returns a G-floating number. 


floating-point-input-value 
OpenVMS usage _ floating_point 


type F_fioating, D_floating, G_floating 
access read only 
mechanism by reference 


Input value. The floating-point-input-value argument is the address of 

a floating-point number that contains this input value. For MTH$SQRT, 
floating-point-input-value specifies an F-floating number. For MTH$DSQRT, 
floating-point-input-value specifies a D-floating number. For MTH$GSQRT, 
floating-point-input-value specifies a G-floating number. 


The square root of X is computed as follows: 


If X < 0, an error is signaled. 
Let X= 2% «F 
where: 


MTH$xSQRT 


K is the exponential part of the floating-point data 
F is the fractional part of the floating-point data 
If K is even: 
Xela Pk 
zSQRT(X) = QP x zSQRT(F), 
1/2<F <1, where P = K/2 
If K is odd: 
X = 2(2*P+)l) , pH 9(2*P+2) , (F/2), 
zSQRT(X) = 2+) « zSQRT(F/2), 
1/4<F/2 < 1/2, where p = (K-1)/2 
Let F' = Ax F + B, when K is even: 
A = 0.95F6198 (hex) 
B = 0.6BA5918 (hex) 
Let F! = Ax (F/2) + B, when K is odd: 
A = 0.D413CCC (hex) 
B = 0.4C1E248 (hex) 
Let K’ = P, when K is even 
Let K’ = P+1, when K is odd 


Let Y(0| = 2%" « F' be a straight line approximation within the given interval 
using coefficients A and B which minimize the absolute error at the midpoint and 
endpoint. | 


Starting with Y[0O], n Newton-Raphson iterations are performed: 
Y[n+ 1] =1/2* (Y|[n] + X/Y[n)}) 
where n = 2, 3, or 3 for z = F-floating, D-floating, or G-floating, respectively. 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HSQRT. 


Condition Values Signaled 


SS$_ROPRAND Reserved operand. The MTH$xSQRT procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$_ SQUROONEG Square root of negative number. Argument 
floating-point-input-value is less than 0.0. 
LIB$SIGNAL copies the floating-point reserved 

: operand to the mechanism argument vector 

CHF$L_MCH SAVRO/R1. The result is the 
floating-point reserved operand unless you have 
written a condition handler to change CHF$L_ 
MCH_SAVRO/R1. 
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MTH$xTAN 


MTH$xTAN—Tangent of Angle Expressed in Radians 


Format 


JSB Entries 


Returns 


Arguments 


Description 
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The Tangent of Angle Expressed in Radians routine returns the tangent of a 
given angle (in radians). 


MTH$TAN angle-in-radians 
MTH$DTAN _ angle-in-radians 
MTH$GTAN  angle-in-radians 


Each of the above formats accepts one of the floating-point types as input. 


MTH$TAN_R4 

MTH$DTAN_R7 

MTH$GTAN_R7 

Each of the above JSB entries accepts one of the floating-point types as input. 


OpenVMS usage  floating_point 


type F floating, D_floating, G_floating 
access write only 
mechanism by value 


The tangent of the angle specified by angle-in-radians. MTH$TAN returns 
an F-floating number. MTH$DTAN returns a D-floating number. MTH$GTAN 


returns a G-floating number. 


angle-in-radians 
OpenVMS usage _ floating_point 


type EF floating, D_floating, G_floating 
access read only 
mechanism by reference 


The input angle (in radians). The angle-in-radians argument is the address of 
a floating-point number that is this angle. For MTH$TAN, angle-in-radians 
specifies an F-floating number. For MTH$DTAN, angle-in-radians specifies a 
D-floating number. For MTH$GTAN, angle-in-radians specifies a G-floating 
number. 


When the input argument is expressed in radians, the tangent function is 
computed as follows: 


1. If |X| < 2°-f/2), then zTAN(X) = X (see the section on MTH$zCOSH for the 
definition of f) 


MTH$xTAN 


2. Otherwise, call MTH$zSINCOS to obtain zSINCX) and zCOS(X); then 
a. If zCOS(X) = 0, signal overflow 
b. Otherwise, zTAN(X) = zSIN(X)/zCOS(X) 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HTAN. 


Condition Values Signaled 


SS$ ROPRAND Reserved operand. The MTH$xTAN procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


MTH$_FLOOVEMAT Floating-point overflow in Math Library. 
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MTH$xTAND—Tangent of Angle Expressed in Degrees 


The Tangent of Angle Expressed in Degrees routine returns the tangent of a given. 
angle (in degrees). 


Format 
MTH$TAND  angle-in-degrees 
MTH$DTAND  angle-in-degrees 
MTH$GTAND  angle-in-degrees 


Each of the above formats accepts one of the floating-point types as input. 


JSB Entries 
MTHS$TAND_R4 


MTH$DTAND_R7 
MTH$GTAND_R7 
Each of the above JSB entries accepts one of the floating-point types as input. 


Returns 


OpenVMS usage  floating_point 

type EF floating, D_floating, G_floating 
access write only 

mechanism by value 


Tangent of the angle specified by angle-in-degrees. MTH$TAND returns an 
F-floating number. MTH$DTAND returns a D-floating number. MTH$GTAND 
returns a G-floating number. 


Arguments 


angle-in-degrees 

OpenVMS usage  floating_point 

type F_flioating, D_floating, G_floating 
access read only 

mechanism by reference 


The input angle (in degrees). The angle-in-degrees argument is the address of 
a floating-point number which is this angle. For MTH$TAND, angle-in-degrees 
specifies an F-floating number. For MTH$DTAND, angle-in-degrees specifies a 
D-floating number. For MTH$GTAND, angle-in-degrees specifies a G-floating 
number. 


Description 


When the input argument is expressed in degrees, the tangent function is 
computed as follows: 


1. If |X| < (180/z) « 2-2/-) and underflow signaling is enabled, underflow is 
signaled (see the section on MTH$zCOSH for the definition of e). 


2. Otherwise, if |X| < (180/z) + 2‘-£/2), then zTAN D(X) = (2/180) * X. See the 
description of MTH$zCOSH for the definition of f. 
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3. Otherwise, call MTH$zSINCOSD to obtain zSIND(X) and zCOSD(X). 
a. Then, if zCOS D(X) = 0, signal overflow 
b. Else, zTAN D(X) = zSIND(X)/zCOSD(X) 


-The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HTAND. 


Condition Values Signaled 


SS$_ROPRAND 


MTH$_FLOOVEMAT 
MTH$_FLOUNDMAT 


Reserved operand. The MTH$xTAND procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a _ 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 


Floating-point overflow in Math Library. 
Floating-point underflow in Math Library. 


AATLI 4 Ad 


MTH$xTANH 


MTH$xTANH—Compute the Hyperbolic Tangent 


The Compute the Hyperbolic Tangent routine returns the hyperbolic tangent of 
the input value. 


Format 
MTH$TANH _ floating-point-input-value 
MTH$DTANH __ floating-point-input-value 
MTH$GTANH _ floating-point-input-value 


Each of the above formats accepts one of the floating-point types as input. 


Returns 


OpenVMS usage floating_point 

type F_floating, D_floating, G_fioating 
access write only 

mechanism by value 


The hyperbolic tangent of floating-point-input-value. MTH$TANH returns an 
F-floating number. MTH$DTANH returns a D-floating number. MTH$GTANH 
returns a G-floating number. Unlike the other three routines, MTH$HTANH 
returns the hyperbolic tangent by reference in the h-tanh argument. 


Arguments 


floating-point-input-value 

OpenVMS usage  floating_point 

type F_floating, D_floating, G_floating 
access read only 

mechanism by reference 


The input value. The floating-point-input-value argument is the address 

of a floating-point number that contains this input value. For MTH$TANH, 
floating-point-input-value specifies an F-floating number. For MTH$DTANH, 
floating-point-input-value specifies a D-floating number. For MTH$GTANH, 
floating-point-input-value specifies a G-floating number. 


Description 


In calculating the hyperbolic tangent of x, the values of g and h are: 


Z g h 

F 12 10 
D 28 21 
G 26 20 
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For MTH$TANH, MTH$DTANH, and MTH$GTANH the hyperbolic tangent of x 
is then computed as follows: 


Value of x 
jn|<2-9 
2-9 < |X| <0.5 


0.5<|X| < 1.0 


10<|X|<h 
h<|X| 


Hyperbolic Tangent Returned 


xX 

tT AN H(X) = X+ X°* R(X”), where R(X?) is a rational 
function of X?. 

sTANH(X) = 2TANH(zHI) + sTANH(zLO)+*C/B 
where C = 1-— 2cTANH (HI) *cTANA(zH]), 
B=1+sTANH(zHI) *xzTANA(zLO), 

tHI = 1/2+ N/16+ 1/32 for N=0,1....,7, 

and <LO = X —- «HI. 

2TANH(X) = (txEXP(2* X) —1)/(cEXP(2* X) +1) 
tTANH(X) = sign(X) «1 


The routine description for the H-floating point version of this routine is listed 
alphabetically under MTH$HTANH. 


Condition Value Signaled 


SS$_ROPRAND 


Reserved operand. The MTH$xTANH procedure 
encountered a floating-point reserved operand 
due to incorrect user input. A floating-point 
reserved operand is a floating-point datum with a 
sign bit of 1 and a biased exponent of 0. Floating- 
point reserved operands are reserved for future 
use by Digital. 
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MTHSUMAX—Compute Unsigned Maximum 


The Compute Unsigned Maximum routine computes the unsigned longword 
maximum of n unsigned longword arguments, where n is greater than or equal to 


1. 
Format 
MTH$UMAX argument [argument....] 
Returns 
OpenVMS usage longword_unsigned 
type longword (unsigned) 
access write only 
mechanism by value 
Maximum value returned by MTH$UMAX. 
Arguments 
argument 
OpenVMS usage longword_unsigned 
type longword (unsigned) 
access read only 
mechanism by reference 


Argument whose maximum MTH$UMAX computes. Each argument argument 
is an unsigned longword that contains one of these values. 


argument 

OpenVMS usage longword_unsigned 
type longword (unsigned) 
access read only 
mechanism by reference 


Additional arguments whose maximum MTH$UMAX computes. Each argument 
argument is an unsigned longword that contains one of these values. 


Description 
MTH$UMAX is the unsigned version of MTH$JMAX0. 


Condition Values Returned 


None. 
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MTHSUMIN—Compute Unsigned Minimum 


Format 


Returns 


Arguments 


Description 


The Compute Unsigned Minimum routine computes the unsigned longword 
minimum of n unsigned longword arguments, where n is greater than or equal to 
1. 


MTH$UMIN argument [argument....] 


OpenVMS usage longword_unsigned 


type longword (unsigned) 
access write only 
mechanism by value 


Minimum value returned by MTH$UMIN. 


argument 

OpenVMS usage longword_unsigned 
type longword (unsigned) 
access read only 
mechanism by reference 


Argument whose minimum MTH$UMIN computes. Each argument argument is 
an unsigned longword that contains one of these values. 


argument 

OpenVMS usage longword_unsigned 
type longword (unsigned) 
access read only 
mechanism by reference 


Additional arguments whose minimum MTH$UMIN computes. Each argument 
argument is an unsigned longword that contains one of these values. 


MTH$UMIN is the unsigned version of MTH$JMINO. 


Condition Values Returned 


None. 
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Vector MTHS Reference Section 


The Vector MTH$ Reference Section provides detailed descriptions of two sets 

of vector routines provided by the OpenVMS RTL Mathematics (MTH$) Facility, 
BLAS Level 1 and FOLR. The BLAS Level 1 are the Basic Linear Algebraic 
Subroutines designed by Lawson, Hanson, Kincaid, and Krogh (1978). The FOLR 
(First Order Linear Recurrence) routines provide a vectorized algorithm for the 
linear recurrence relation. 


BLAS1$VIxAMAX 


BLAS1$VIxAMAX—Obtain the Index of the First Element of a Vector 


Format 


Returns 


Arguments 


Having the Largest Absolute Value 


The Obtain the Index of the First Element of a Vector Having the Largest 
Absolute Value routines find the index of the first occurrence of a vector element 
having the maximum absolute value. 


BLAS1I$VISAMAX _ n ,x ,incx 
BLAS1$VIDAMAX _ n ,x ,incx 
BLAS1ISVIGAMAX _n ,x ,incex 
BLAS1$VICAMAX _ n,x ,incx 
BLAS1$VIZAMAX _n ,x ,incex 
BLAS1$VIWAMAX _n ,x ,incx 


Use BLASI$VISAMAX for single-precision real operations. Use 
BLAS1I$VIDAMAX for double-precision real (D-floating) operations and 
BLAS1$VIGAMAX for double-precision real (G-floating) operations. 


Use BLASI$VICAMAX for single-precision complex operations. Use 
BLAS1I$VIZAMAX for double-precision complex (D-floating) operations and 
BLAS1$VIWAMAX for double-precision complex (G-floating) operations. 


OpenVMS usage  longword_signed 


type longword integer (signed) 
access write only 
mechanism by value 


For the real versions of this routine, the function value is the index of the first 
occurrence of a vector element having the maximum absolute value, as follows: 


\z;| = max {|z,| for 7 = 12) axyn} 


For the complex versions of this routine, the function value is the index of the 
first occurrence of a vector element having the largest sum of the absolute values 
of the real and imaginary parts of the vector elements, as follows: 


|Re(z;)| + [Im(2;)| = max {|Re(x,)| + |Im(z;)| for 7 = 1,2,...,n} 


n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vector z. The n argument is the address of a signed 
longword integer containing the number of elements. If you specify a negative 
value or 0 for n, 0 is returned. | 
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x 

OpenVMS usage floating_point or complex_number 

type F_ floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access read only 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. This argument is an array of length at least 


1+ (n — 1) * lene 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


Specify the data type as follows: 


Routine Data Type for x 
BLAS1$VISAMAX F-floating real 
BLAS1$VIDAMAX D-floating real 
BLAS1$VIGAMAX G-floating real 
BLAS1$VICAMAX F-floating complex 
BLAS1I$VIZAMAX D-floating complex 
BLASI$VIWAMAX G-floating complex 


If n is less than or equal to 0, then imax is 0. 


incx 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than or equal to 0, then z is referenced forward in array x; that is, 2; is referenced 
as: 


a(1-+ (¢ — 1) *incz) 


where: 

x = array specified in x 

l = element of the vector z 

incx = increment argument for the array x specified in inex 


If you specify a negative value for inex, it is interpreted as the absolute value of 
incx. 


Description 


Example 


BLAS1$VIxAMAX 


BLASI$VISAMAX, BLAS1$VIDAMAX, and BLAS1$VIGAMAX find the index, 1, 
of the first occurrence of a vector element having the maximum absolute value. 


~BLAS1$VICAMAX, BLAS1$VIZAMAX, and BLAS1$VIWAMAX find the index, /, 


of the first occurrence of a vector element having the largest sum of the absolute 
values of the real and imaginary parts of the vector elements. 


Vector z contains n elements that are accessed from array x by stepping inex 
elements at a time. The vector z is a real or complex single-precision or double- 
precision (D and G) n-element vector. The vector can be a row or a column of a 
matrix. Both forward and backward indexing are permitted. 


BLAS1$VISAMAX, BLASI$VIDAMAX, and BLAS1$VIGAMAX determine the 
smallest integer z of the n-element vector x such that: 


|| = max {|z;| for 7 = 1,2,...,n} 


BLASI$VICAMAX, BLASI$VIZAMAX, and BLASI$VIWAMAX determine the 
smallest integer z of the n-element vector z such that: 


[Re(z;)| + |Im(z;)| = max {|Re(z,;)| + |Im(z;)| for 7 = 1,2,...,n} 


You can use the BLASI$VIxAMAX routines to obtain the pivots in Gaussian 
elimination. 


The public-domain BLAS Level 1 IxAMAX routines require a positive value for 
inex. The Run-Time Library BLAS Level 1 routines interpret a negative value 
for inex as the absolute value of inex. 


The algorithm does not provide a special case for inex = 0. Therefore, specifying 
0 for inex has the effect of setting imax equal to 1 using vector operations. 


C 
C To obtain the index of the element with the maximum 
C absolute value. 
C 
INTEGER IMAX,N, INCX 
REAL X(40) 
INCX = 2 
N = 20 
IMAX = BLASISVISAMAX(N,X, INCX) 
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BLAS1$VxASUM 


BLAS1$VxASUM—Obtain the Sum of the Absolute Values of the 


Format 


Returns 


Arguments 
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Elements of a Vector 


The Obtain the Sum of the Absolute Values of the Elements of a Vector routines 
determine the sum of the absolute values of the elements of the n-element vector 
Z. 


BLAS1$VSASUM nx ,incx 
BLAS1$VDASUN __n ,x ,incx 
BLAS1$VGASUM _n ,x ,incex 
BLAS1$VSCASUM _n ,.x ,incx 
BLAS1$VDZASUM _n ,x ,incx 
BLAS1$VGWASUNM _n ,x ,incx 


Use BLASI$VSASUM for single-precision real operations. Use BLASI$VDASUM 
for double-precision real (D-floating) operations and BLASI$VGASUM for double- 
precision real (G-floating) operations. 


Use BLASI$VSCASUM for single-precision complex operations. Use 
BLAS1I$VDZASUM for double-precision complex (D-floating) operations and 
BLASI$VGWASUM for double-precision complex (G-floating) operations. 


OpenVMS usage floating_point 


type F floating, D_floating, or G_floating real 
access write only 
mechanism by value 


The function value, called sum, is the sum of the absolute values of the elements 
of the vector z. The data type of the function value is a real number; for the 
BLAS1$VSCASUM, BLASI$VDZASUM, and BLASI$VGWASUM routines, the 
data type of the function value is the real data type corresponding to the complex 
argument data type. 


n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vector z to be added. The n argument is the address of a 
signed longword integer containing the number of elements. 


x 

OpenVMS usage _floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex | 

access read only 

mechanism . by reference, array reference 


Description 


BLAS1$VxASUM 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. This argument is an array of length at least 


1+ (n —1) * |tnca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


Specify the data type as follows: 


Routine Data Type for x 
BLASI$VSASUM F-floating real 
BLAS1$VDASUM D-floating real 
BLAS1$VGASUM G-floating real 
BLASI$VSCASUM | F-floating complex 
BLAS1$VDZASUM D-floating complex 
BLAS1$VGWASUM G-floating complex 


If n is less than or equal to 0, then sum is 0.0. 


incx 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than or equal to 0, then z is referenced forward in array x; that is, 2; is referenced 
in: 


a(1+ (2 — 1) *incz) 


where: 

x = array specified in x 

L = element of the vector z 

incx = increment argument for the array x specified in inex 


If you specify a negative value for inex, it is interpreted as the absolute value of 
inex. 


BLAS1$VSASUM, BLAS1$VDASUM, and BLASI$VGASUM obtain the sum of 
the absolute values of the elements of the n-element vector z. BLASI$VSCASUM, 
BLAS1$VDZASUM, and BLAS1$VGWASUM obtain the sum of the absolute 
values of the real and imaginary parts of the elements of the n-element vector z. 


Vector x contains n elements that are accessed from array x by stepping inex 
elements at a time. The vector z is a real or complex single-precision or double- 


precision (D and G) n-element vector. The vector can be a row or a column of a 


matrix. Both forward and backward indexing are permitted. 


BLAS1$VxASUM 


Example 
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BLAS1$VSASUM, BLAS1$VDASUM, and BLASI$VGASUM compute the sum of 
the absolute values of the elements of z, which is expressed as follows: 


doget [2a| = |21| + [zo] +... + [an| 


BLASI$VSCASUM, BLAS1$VDZASUM, and BLASI$VGWASUM compute the 
sum of the absolute values of the real and imaginary parts of the elements of z, 
which is expressed as follows: 


Doiai (|| + [bs]) = (Joa + [b1]) + (laal + [b2l) +--+ (lanl + [bnl) 
where |z;| = (a;, 5;) 
and |a;| + |6;| = |real| + |imaginary| 


The public-domain BLAS Level 1 xASUM routines require a positive value for 
incx. The Run-Time Library BLAS Level 1 routines interpret a negative value 
for inex as the absolute value of inex. 


The algorithm does not provide a special case for inex = 0. Therefore, specifying 
0 for inex has the effect of computing n « |z;| using vector operations. 


Rounding in the summation occurs in a different order than in a sequential 
evaluation of the sum, so the final result may differ from the result of a sequential 
evaluation. 


C 
C To obtain the sum of the absolute values of the 
C elements of vector x: 
C 
INTEGER N, INCX 
REAL X(20),SUM 
INCX = 1 
N = 20 
SUM = BLAS1SVSASUM(N,X, INCX) 


BLAS1$VxAXPY 


BLAS1$VxAXPY—Multiply a Vector by a Scalar and Add a Vector 


Format 


Returns 


Arguments 


The Multiply a Vector by a Scalar and Add a Vector routines compute az + y, 
where a is a scalar number and z and y are n-element vectors. 


BLAS1$VSAXPY n,a_,x ,incx ,y ,incy 
BLAS1$VDAXPY n,a,x ,incx ,y ,incy 
BLASI$VGAXPY na ,x ,incx ,y ,incy 
BLAS1$VCAXPY n,a_,x ,incx ,y ,incy 
BLAS1$VZAXPY n,a,x ,incx ,y ,incy 
BLAS1$VWAXPY na ,x ,incx ,y ,incy 


Use BLASI$VSAXPY for single-precision real operations. Use BLASI$VDAXPY 
for double-precision real (D-floating) operations and BLAS1$VGAXPY for double- 
precision real (G-floating) operations. 


Use BLAS1$VCAXPY for single-precision complex operations. Use 
BLAS1$VZAXPY for double-precision complex (D-floating) operations and 
BLASI$VWAXPY for double-precision complex (G-floating) operations. 


None. 

n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vectors zx and y. The n argument is the address of a 
signed longword integer containing the number of elements. If n is less than or 
equal to 0, then y is unchanged. 


a 

OpenVMS usage  floating_point or complex_number 

type F_floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access read only 

mechanism by reference, array reference 


Scalar multiplier for the array x. The a argument is the address of a floating- 

point or floating-point complex number that is this multiplier. If a equals 0, then 
y is unchanged. If a shares a memory location with any element of the vector y, 
results are unpredictable. Specify the same data type for arguments a, x, and y. 
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x 

OpenVMS usage _ floating_point or complex_number 

type F_ floating, D_floating, G_floating real or F_floating, 
D_flioating, G_floating complex 

access read only | 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. The length of this array is at least 


1+ (n — 1) # |incz| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


Specify the data type as follows: 


Routine Data Type for x 
BLAS1$VSAXPY F-floating real 
BLASI$VDAXPY D-floating real 
BLAS1$VGAXPY G-floating real 
BLAS1I$VCAXPY F-floating complex 
BLASI$VZAXPY D-floating complex 
BLAS1$VWAXPY G-floating complex 


If any element of z shares a memory location with an element of y, the results 
are unpredictable. 


incx 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than or equal to 0, then =z is referenced forward in array x; that is, z; is referenced 
in: 


a(1+ (2 — 1) *tncz) 


where: 

x =. array specified in x 

1 = element of the vector z 

incx = increment argument for the array x specified in inex 


If inex is less than 0, then xz is referenced backward in array x; that is, z; is 
referenced in: 


t(1+ (n —12) * |incz}) 


BLAS1$VxAXPY 


where: 

x = array specified in x 

n = number of vector elements specified in n 

L = element of the vector x 

incx = increment argument for the array x specified in inex 

y 

OpenVMS usage floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access modify 

mechanism by reference, array reference 


On entry, array containing the elements to be accessed. All elements of array 

y are accessed only if the increment argument of y, called incy, is 1. The y 
argument is the address of a floating-point or floating-point complex number that 
is this array. The length of this array is at least 


1+ (n—1) # |ency| 


where: 
n = number of vector elements specified in n 
incy = increment argument for the array y specified in incy 


Specify the data type as follows: 


Routine Data Type for y 
BLASI$VSAXPY F-floating real 
BLAS1I$VDAXPY D-floating real 
BLAS1$VGAXPY G-floating real 
BLASI$VCAXPY F-floating complex 
BLASI$VZAXPY D-floating complex 
BLASI$VWAXPY | G-floating complex 


If n is less than or equal to 0, then y is unchanged. If any element of z shares a 
memory location with an element of y, the results are unpredictable. 


On exit, y contains an array of length at least 


1+ (n— 1) * |ency| 


where: 
n = number of vector elements specified in n 
incy = increment argument for the array y specified in incy 


After the call to BLASI$VxAXPY, y; is set equal to 


y; +a * Xj. 
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Description 
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where: 

y = _ the vector y 

it = element of the vector x or y 

a =. scalar multiplier for the vector z specified in a 
x = the vector z 

incy 

OpenVMS usage longword_signed 

type longword integer (signed) 

access read only 

mechanism by reference 


Increment argument for the array y. The incy argument is the address of a 
signed longword integer containing the increment argument. If incy is greater 
than or equal to 0, then y is referenced forward in array y; that is, y is referenced 
in: 


y(1+ (2 — 1) * ancy) 


where: 

y = array specified in y 

7 = element of the vector y 

incy = increment argument for the array y specified in incy 


If incy is less than 0, then y is referenced backward in array y; that is, y; is 
referenced in: 


y(1+ (n —7) * |ency)) 


where: 

y = array specified in y 

n = number of vector elements specified in n 

L = element of the vector y 

incy = increment argument for the array y specified in incy 


BLAS1$VxAXPY multiplies a vector z by a scalar, adds to a vector y, and stores 
the result in the vector y. This is expressed as follows: 


y-az+y 


where a is a scalar number and z and y are real or complex single-precision or 
double-precision (D and G) n-element vectors. The vectors can be rows or columns 
of a matrix. Both forward and backward indexing are permitted. Vectors z and y 
contain n elements that are accessed from arrays x and y by stepping inex and 
incy elements at a time. 


The routine name determines the data type you should specify for arguments a, 
x, and y. Specify the same data type for each of these arguments. 


The algorithm does not provide a special case for inex = 0. Therefore, specifying 
0 for inex has the effect of adding the constant a « x; to all elements of the vector 
y using vector operations. 


Example 


C 
C To compute y=y+2.0*x using SAXPY: 
C 
INTEGER N,INCX, INCY 
REAL X(20), Y¥(20),A 
INCX = 1] 
INCY = 1 
A = 2.0 
N = 20 
CALL BLAS1SVSAXPY(N,A,X,INCX,Y, INCY) 


BLAS1$VxAXPY 
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BLAS1$VxCOPY 


BLAS1$VxCOPY—Copy a Vector 


Format 


Returns 


Arguments 
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The Copy a Vector routines copy n elements of the vector x to the vector y. 


BLAS1$VSCOPY _n ,x ,incx ,y ,incy 
BLAS1$VDCOPY _n ,x ,incx ,y ,incy 
BLAS1$VCCOPY _n ,x ,incx ,y ,incy 
BLASI$VZCOPY _n ,x ,incx ,y ,incy 


Use BLAS1$VSCOPY for single-precision real operations and BLASI$VDCOPY 
for double-precision real (D or G) operations. 


Use BLASI$VCCOPY for single-precision complex operations and 
BLAS1$VZCOPY for double-precision complex (D or G) operations. 


None. 

n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vector z to be copied. The n argument is the address of 
a signed longword integer containing the number of elements in vector zx. If nis 
less than or equal to 0, then y is unchanged. 


x 

OpenVMS usage floating_point or complex_number 

type F_floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access read only 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. This argument is an array of length at least 


1+ (n— 1) * |¢nca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


BLAS1$VxCOPY 


Specify the data type as follows: 


Routine Data Type for x 

BLASI$VSCOPY F-floating real 
BLAS1$VDCOPY _ D-floating or G-floating real 
BLAS1$VCCOPY F-floating complex 
BLAS1$VZCOPY D-floating or G-floating complex 
incx 

OpenVMS usage longword_signed 

type longword integer (signed) 

access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than or equal to 0, then z is referenced forward in array x; that is, 2; is referenced 
in: 


a(1+ (¢ — 1) * inca) 


where: 

x = array specified in x 

L = element of the vector z 

incx = increment argument for the array x specified in inex 


If inex is less than 0, then z is referenced backward in array x; that is, z; is 
referenced in: 


t(1+ (n —2) * |zncz}) 


where: 
= array specified in x 
= number of vector elements specified in n 
l = element of the vector z 
incx = increment argument for the array x specified in inex 
y 
OpenVMS usage floating_point or complex_number 
type EF floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 
access write only 
mechanism by reference, array reference 


Array that receives the copied elements. All elements of array y receive the 
copied elements only if the increment argument of y, called incy, is 1. The y 
argument is the address of a floating-point or floating-point complex number that 
is this array. This argument is an array of length at least 


1+ (n— 1) * lency| 
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where: 
n = number of vector elements specified in n 
incy = increment argument for the array y specified in incy 


Specify the data type as follows: 


Routine Data Type for y 
BLAS1I$VSCOPY F-floating real 
BLAS1$VDCOPY D-floating or G-floating real 
BLAS1$VCCOPY F-floating complex 
BLASI$VZCOPY D-floating or G-floating complex 


If n is less than or equal to 0, then y is unchanged. If inex is equal to 0, then 
each y; is set to x1. If incy is equal to 0, then y; is set to the last referenced 
element of z. If any element of z shares a memory location with an element of y, 
the results are unpredictable. (See the Description section for a special case that 
does not cause unpredictable results when the same memory location is shared by 
input and output.) 


incy 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array y. The incy argument is the address of a 
signed longword integer containing the increment argument. If incy is greater 
than or equal to 0, then y is referenced forward in array y; that is, y; is referenced 
in: 

y(1+ (¢ — 1) *incy) 


where: 


y array specified in y 
l element of the vector y 


If incy is less than 0, then y is referenced backward in array y; that is, y; is 
referenced in: 


y(1+ (n —2) # jency)) 


where: 

y = array specified in y 

n = number of vector elements specified in n 

L = element of the vector y 

incy = increment argument for the array y specified in incy 


Description 


BLAS1$VxCOPY 


BLASI$VSCOPY, BLAS1$VDCOPY, BLAS1$VCCOPY, and BLAS1$VZCOPY copy 
n elements of the vector xz to the vector y. Vector x contains n elements that are 
accessed from array x by stepping inex elements at a time. Both z and y are real 
or complex single-precision or double-precision (D and G) n-element vectors. The 
vectors can be rows or columns of a matrix. Both forward and backward indexing 
are permitted. | 


If you specify 0 for inex, BLAS1$VxCOPY initializes all elements of ytoa 
constant. 


If you specify -inex for incy, the vector z is stored in reverse order in y. In this 
case, the call format is as follows: 


CALL BLASISVxCOPY (N,X,INCX,Y,-INCX) 


It is possible to move the contents of a vector up or down within itself and not 
cause unpredictable results even though the same memory location is shared 
between input and output. To do this when 7 is greater than /, call the routine 
BLAS1$VxCOPY with incz = incy > 0 as follows: 


CALL BLAS1$VxCOPY (N,X(I),INCX,X(J), INCX) 
The preceding call to BLASI$VxCOPY moves: 
a(t), 2(¢-+1*inca),...2(¢ + (n — 1) * inca) 

to 

t(j), {7 +1 inca), ...2(7 + (n — 1) *tncz) 


If i is less than j, specify a negative value for inex and incy in the call to 
BLAS1$VxCOPY, as follows. The parts that do not overlap are unchanged. 


CALL BLASISVxCOPY (N,X(I),-INCX,X(J) ,-INCX) 


Note 


BLAS1$VxCOPY does not perform floating operations on the input 
data. Therefore, floating reserved operands are not detected by 
BLAS1$VxCOPY. 
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Example 
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QAAAN QAAAA 


AAANQ 


To copy a vector x to a vector y uSing BLASISVSCOPY: 


INTEGER N, INCX, INCY 

REAL X(20),Y(20) 

INCX = 1 

INCY = 1 

N = 20 

CALL BLAS1SVSCOPY(N,X,INCX,Y,INCY) 


.To move the contents of X(1),X(3),X(5),...,X(2N-1) 


to X(3),X(5),...,X(2N+t1) and leave x unchanged: 
CALL BLASISVSCOPY(N,X,-2,X(3),-2)) 


To move the contents of X(2),X(3),...,X(100) to 
X(1),X(2),...,X(99)and leave x(100) unchanged: 


CALL BLASISVSCOPY(99,X(2),1,X,1)) 


To move the contents of X(1),X(2),X(3),...,X(N) to 
Y(N),Y(N-1),...,Y 


CALL BLASI$VSCOPY(N,X,1,Y,-1)) 
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BLAS1$VxDOTx—Obtain the Inner Product of Two Vectors 


Format 


Returns 


The Obtain the Inner Product of Two Vectors routines return the dot product of 
two n-element vectors, x and y. 


BLASI$VSDOT _n,x ,inex ,y ,incy 
BLAS1$VDDOT _n ,x , inex ,y ,incy 
BLAS1$VGDOT _n ,x ,inex ,y ,incy 
BLAS1$VCDOTU _n ,x ,inex ,y ,incy 
BLASI$VCDOTC _n ,x ,incx ,y ,incy 
BLAS1$VZDOTU nx , inex ,y ,incy 
BLASI$VWDOTU _n ,x ,incx ,y ,incy 
BLAS1$VZDOTC _n x ,inex ,y ,incy 
BLASISVWDOTC _n,x ,incx ,y ,incy 


Use BLASI$VSDOT to obtain the inner product of two single-precision real 
vectors. : 


Use BLASI$VDDOT to obtain the inner product of two double-precision (D- 
floating) real vectors. Use BLASI$VGDOT to obtain the inner product of two 
double-precision (G-floating) real vectors. 


Use BLAS1$VCDOTU to obtain the inner product of two single-precision complex 
vectors (unconjugated). 


Use BLASI$VCDOTC to obtain the inner product of two single-precision complex 
vectors (conjugated). 


Use BLASI$VZDOTU to obtain the inner product of two double-precision (D- 
floating) complex vectors (unconjugated). Use BLASI$VWDOTU to obtain the 
inner product of two double-precision (G-floating) complex vectors (unconjugated). 


Use BLASI$VZDOTC to obtain the inner product of two double-precision (D- 
floating) complex vectors (conjugated). Use BLASI$VWDOTC to obtain the inner 
product of two double-precision (G-floating) complex vectors (conjugated). 


OpenVMS usage  floating_point or complex_number 


type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access write only 

mechanism by value 


The function value, called dotpr, is the dot product of two n-element vectors, z 
and y. Specify the same data type for dotpr and the argument x. 
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Arguments 
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n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vector z. The n argument is the address of a signed 
longword integer containing the number of elements. If you specify a value for n 
that is less than or equal to 0, then the value of dotpr is 0.0. 


X 

OpenVMS usage _ floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access read only 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. This argument is an array of length at least 


1+ (n— 1) * |enca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


Specify the data type as follows: 


Routine Data Type for x 
BLAS1$VSDOT F-floating real 
BLAS1$VDDOT D-floating real 
BLAS1$VGDOT G-floating real 
BLASI$VCDOTU and F-floating complex 
BLAS1$VCDOTC 

BLAS1$VZDOTU and D-floating complex 
BLAS1$VZDOTC 

BLAS1$VWDOTU and G-floating complex 
BLAS1I$VWDOTC 

incx 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than 0, then z is referenced forward in array x; that is, z; is referenced in: 


a(1+ (2 — 1) *zncz) 


BLAS1$VxDOTx 


where: 

x = array specified in x 

1 = element of the vector z | 
incx = increment argument for the array x specified in inex 


If inex is less than 0, then z is referenced backward in array x; that is, 2; is 
referenced in: 


z(1+ (n — 2) * |encz}) 


where: 

x = array specified in x 

n = number of vector elements specified in n 

L = element of the vector z 

incx = increment argument for the array x specified in inex 

y 

OpenVMS usage _ floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access read only 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array y are 
accessed only if the increment argument of y, called incy, is 1. The y argument 
is the address of a floating-point or floating-point complex number that is this 
array. This argument is an array of length at least 


1+ (n—1) * lency| 


where: 
n = number of vector elements specified in n 
incy = increment argument for the array y specified in incy 


Specify the data type as follows: 


Routine Data Type for y 
BLAS1$VSDOT F-floating real 
BLAS1$VDDOT D-floating real 
BLAS1$VGDOT G-floating real 
BLAS1$VCDOTU and F-floating complex 
BLASI$VCDOTC 

BLASI$VZDOTU and D-floating complex 
BLAS1$VZDOTC 

BLASI$VWDOTU and G-floating complex 
BLASI$VWDOTC 
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Description 
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incy 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array y. The incy argument is the address of a 
signed longword integer containing the increment argument. If incy is greater 
than or equal to 0, then y is referenced forward in array y; that is, y; is referenced 
In: 


y(1+ (2 — 1) * incy) 


where: 

y = array specified in y 

1 = element of the vector y 

incy = increment argument for the array y specified in incy 


If incy is less than 0, then y is referenced backward in array y; that is, y; is 
referenced in: 


y(1+ (n —2) « |ency]} 


where: 

y = array specified in y 

n = number of vector elements specified in n 

7 = element of the vector y 

incy = increment argument for the array y specified in incy 


The unconjugated versions of this routine, BLAS1$VSDOT, BLAS1$VDDOT, 
BLAS1$VGDOT, BLAS1$VCDOTU, BLASI$VZDOTU, and BLASI$VWDOTU 
return the dot product of two n-element vectors, z and y, expressed as follows: 


Z y= 21y1 + TQYQ +... + IZnyn 


The conjugated versions of this routine, BLASI$VCDOTC, BLASI$VZDOTC, and 
BLAS1$VWDOTC return the dot product of the conjugate of the first n-element 
vector with a second n-element vector, as follows: 


Z y= 2141 + Toya +... + Znyn 


Vectors z and y contain n elements that are accessed from arrays x and y by 
stepping inex and incy elements at a time. The vectors z and y can be rows or 
columns of a matrix. Both forward and backward indexing are permitted. 


The routine name determines the data type you should specify for arguments x 
and y. Specify the same data type for these arguments. 


Rounding in BLAS1$VxDOTx occurs in a different order than in a sequential 
evaluation of the dot product. The final result may differ from the result of a 
sequential evaluation. 


Example 


C 
C To compute the dot product of two vectors, x and y, 
C and return the result in DOTPR: 
C 
INTEGER INCX, INCY 
REAL X(20),¥(20),DOTPR 


INCX = 1 
INCY = 1 
N = 20 


DOTPR = BLAS1$VSDOT(N,X,INCX,Y,INCY) 
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BLAS1$VxNRM2—Obtain the Euclidean Norm of a Vector 


Format 


Returns 


Arguments 


The Obtain the Euclidean Norm of a Vector routines obtain the Euclidean norm 
of an n-element vector zx, expressed as follows: 


Vai taht... + 22 


BLAS1$VSNRMZ2__n x ,incx 
BLAS1$VDNRM2__n ,x ,incx 
BLAS1$VGNRMZ2__n x ,incx 
BLAS1$VSCNRM2 __n ,x , inex 
BLASI$VDZNRM2 __n .x ,incx 
BLAS1$VGWNRMZ__o x ,incx 


Use BLASI$VSNRM2 for single-precision real operations. Use BLASI$VDNRM2 
for double-precision real (D-floating) operations and BLASI$VGNRM2 for double- 
precision real (G-floating) operations. 


Use BLASI$VSCNRM2 for single-precision complex operations. Use 
BLAS1$VDZNRM2 for double-precision complex (D-floating) operations and 
BLAS1$VGWNRM2 for double-precision complex (G-floating) operations. 


OpenVMS usage floating point 


type F floating, D_floating, or G_floating real 
access write only 
mechanism by value 


The function value, called e_norm, is the Euclidean norm of the vector z. The 
data type of the function value is a real number; for the BLASI$VSCNRM2, 
BLASI$VDZNRM2, and BLAS1$VGWNRM2 routines, the data type of the 
function value is the real data type corresponding to the complex argument data 


type. 7 


n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vector z to be processed. The n argument is the address 
of a signed longword integer containing the number of elements. 


x 

OpenVMS usage floating_point or complex_number 

type F_floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access read only 


mechanism by reference, array reference 


Description 


BLAS1$VxNRM2 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. This argument is an array of length at least 


1+ (n — 1) * |¢nca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


Specify the data type as follows: 


Routine Data Type for x 
BLAS1$VSNRM2 F-floating real 
BLASI$VDNRM2 D-floating real 
BLAS1$VGNRM2 G-floating real 
BLAS1$VSCNRM2 F-floating complex 
BLAS1$VDZNRM2 D-floating complex — 
BLAS1$VGWNRM2 G-floating complex 


If n is less than or equal to 0, then e_norm is 0.0. 


incx 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than or equal to 0, then z is referenced forward in array x; that is, z; is referenced 
In: 


a(1+ (2-1) *2tncz) 


where: 

x = array specified in x 

L = element of the vector z 

incx = increment argument for the array x specified in inex 


If you specify a negative value for inex, it is interpreted as the absolute value of 
inex. 


BLAS1$VxNRM2 obtains the Euclidean norm of an n-element vector z, expressed 
as follows: 


s/t t+ oh +... + 22 


Vector z contains n elements that are accessed from array x by stepping inex 
elements at a time. The vector z is a real or complex single-precision or double- 
precision (D and G) n-element vector. The vector can be a row or a column of a 
matrix. Both forward and backward indexing are permitted. 


BLAS1$VxNRM2 


Example 


The public-domain BLAS Level 1 xNRM2 routines require a positive value for 
incx. The Run-Time Library BLAS Level 1 routines interpret a negative value 
for inex as the absolute value of inex. 


The algorithm does not provide a special case for inex = 0. Therefore, specifying 
0 for inex has the effect of using vector operations to set e_norm as follows: 


e-norm = n°? + |z4| 


For BLASI$VDNRM2, BLAS1$VGNRM2, BLASI$VDZNRM2, and 
BLAS1$VGWNRM2 (the double-precision routines), the elements of the vector 

z are scaled to avoid intermediate overflow or underflow. BLASI$VSNRM2 and 
BLAS1I$VSCNRM2 (the single-precision routines) use a backup data type to avoid 
intermediate overflow or underflow. | 


Rounding in BLAS1$VxNRM2 occurs in a different order than in a sequential 
evaluation of the Euclidean norm. The final result may differ from the result of a 
sequential evaluation. 


Cc 
C To obtain the Euclidean norm of the vector x: 


INTEGER INCX,N 

REAL X(20),E NORM 

INCX = 1 7 

N = 20 

E NORM = BLAS1$VSNRM2(N,X,INCX) 
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BLAS1$VxROT—Apply a Givens Plane Rotation 


Format 


Returns 


Arguments 


The Apply a Givens Plane Rotation routines apply a Givens plane rotation to a 
pair of n-element vectors z and y. 


BLAS1$VSROT _n ,x ,inex ,y ,incy ,c S 
BLASI$VDROT nx ,incx ,y ,incy ,c ,s 
BLAS1$VGROT nx ,incx ,y ,incy ,c ,s_ 
BLAS1$VCSROT _n ,x ,incex ,y ,incy ,c ,s 
BLAS1$VZDROT _n ,x ,inex ,y ,incy ,c ,s 
BLAS1$VWGROT _n ,x ,incx ,y ,incy ,c ,s 


Use BLAS1$VSROT for single-precision real operations. Use BLASI$VDROT 
for double-precision real (D-floating) operations and BLASI$VGROT for double- 
precision real (G-floating) operations. 


Use BLAS1$VCSROT for single-precision complex operations. Use 
BLAS1$VZDROT for double-precision complex (D-floating) operations and 
BLASI$VWGROT for double-precision complex (G-floating) operations. 
BLASI$VCSROT, BLAS1$VZDROT, and BLASI$VWGROT are real rotations 
applied to a complex vector. 


None. 

n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vectors z and y to be rotated. The n argument is the 
address of a signed longword integer containing the number of elements to be 
rotated. If n is less than or equal to 0, then x and y are unchanged. 


X 

OpenVMS usage _floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access modify 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. On entry, this argument is an array of length at least 


1+ (n—1) * lence 


BLAS1$VxROT 
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where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


Specify the data type as follows: 


Routine Data Type for x 
BLAS1$VSROT F-floating real 
BLAS1$VDROT D-floating real 
BLAS1$VGROT G-floating real 
BLAS1I$VCSROT F-floating complex 
BLAS1$VZDROT D-floating complex 
BLAS1$VWGROT G-floating complex 


If n is less than or equal to 0, then x and y are unchanged. If ¢c equals 1.0 and 
s equals 0, then x and y are unchanged. If any element of z shares a memory 
location with an element of y, then the results are unpredictable. 


On exit, x contains the rotated vector z, as follows: 


Bic +o; + 8 Y, 


where: 

x = array x specified in x 

y =~ array y specified in y 

bce 2=.2,34,n 

C rotation element generated by the BLAS1$VxROTG routines 
s = rotation element generated by the BLAS1$VxROTG routines 
incx | 

OpenVMS usage longword_signed 

type longword integer (signed) 

access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than or equal to 0, then =z is referenced forward in array x; that is, x; is referenced 
in: 


z(1+ (2-1) * inca) 


where: 

x = array specified in x 

L = element of the vector z 

incx = increment argument for the array x specified in inex 


If inex is less than 0, then z is referenced backward in array x; that is, z; is 
referenced in: | 


t(1 + (n— 2) * |tncz|) 
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where: 

x = array specified in x 

n = number of vector elements specified in n 

7 = element of the vector z 

incx = increment argument for the array x specified in inex 

y 

OpenVMS usage _ floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access modify 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array y are 
accessed only if the increment argument of y, called incy, is 1. The y argument 
is the address of a floating-point or floating-point complex number that is this 
array. On entry, this argument is an array of length at least 


1+ (n—1) # |tnca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in incx 


Specify the data type as follows: 


Routine Data Type for y 
BLAS1$VSROT F-floating real 
BLAS1I$VDROT | D-floating real 
BLAS1$VGROT G-floating real 
BLAS1$VCSROT F-floating complex 
BLAS1$VZDROT | D-floating complex 
BLAS1$VWGROT G-floating complex 


If n is less than or equal to 0, then x and y are unchanged. If ¢ equals 1.0 and 
s equals 0, then x and y are unchanged. If any element of z shares a memory 
location with an element of y, then the results are unpredictable. 


On exit, y contains the rotated vector y, as follows: 


Yi — SHEET CHY; 


where: 

x = array x specified in x 

y =~ array y specified in y 

CS eT 2 i 

c = real rotation element (can be generated by the BLASI$VxROTG routines) 
-s = complex rotation element (can be generated by the BLASI$VxROTG 


routines) 


MTH-175 


BLAS1$VxROT 


MTH-176 


incy 

OpenVMS usage  longword_signed 

type | longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array y. The incy argument is the address of a 
signed longword integer containing the increment argument. If incy is greater 
than or equal to 0, then y is referenced forward in array y; that is, y; is referenced 
in: 


y(1 + (2 — 1) * zncy) 


where: 

y = array specified in y 

7 = element of the vector y 

incy = increment argument for the array y specified in incy 


If incy is less than 0, then y is referenced backward in array y; that is, y; is 
referenced in: 


y(1+ (n —2) # |incy]) 


where: 

y = array specified in y 

n = number of vector elements specified in n 

L = element of the vector y 

incy = increment argument for the array y specified in incy 
Cc 

OpenVMS usage floating_point 

type F_floating, D_floating, or G_floating real 
access read only 

mechanism by reference 


First rotation element, which can be interpreted as the cosine of the angle of 
rotation. The c argument is the address of a floating-point or floating-point 
complex number that is this vector element. The c argument is the first rotation 
element generated by the BLASI$VxROTG routines. 


Specify the data type (which is always real) as follows: 


Routine Data Type for c 
- BLAS1$VSROT and F-floating real 

BLAS1$VCSROT 

BLAS1$VDROT and D-floating real 

BLAS1$VZDROT | 

BLAS1$VGROT and G-floating real 

BLAS1$VWGROT 


Description 


Example 


BLAS1$VxROT 


Ss 

OpenVMS usage  floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access read only 

mechanism by reference 


Second rotation element, which can be interpreted as the sine of the angle of 
rotation. The s argument is the address of a floating-point or floating-point 
complex number that is this vector element. The s argument is the second 
rotation element generated by the BLAS1$VxROTG routines. 


Specify the same data type for arguments s and c. 


BLAS1$VSROT, BLAS1$VDROT, and BLASI$VGROT apply a real Givens 

plane rotation to a pair of real vectors. BLASI$VCSROT, BLAS1$VZDROT, and 
BLAS1$VWGROT apply a real Givens plane rotation to a pair of complex vectors. 
The vectors x and y are real or complex single-precision or double-precision (D 
and G) vectors. The vectors can be rows or columns of a matrix. Both forward 
and backward indexing are permitted. The routine name determines the data 
type you should specify for arguments x and y. Specify the same data type for 
each of these arguments. 


The Givens plane rotation is applied to n elements, where the elements to be 
rotated are contained in vectors x and y ( equals 1,2,...,.1). These elements are 
accessed from arrays x and y by stepping inex and incy elements at a time. The 
cosine and sine of the angle of rotation are c and s, respectively. The arguments 
c and s are usually generated by the BLAS Level 1 routine BLASI$VxROTG, 


The BLAS1$VxROT routines can be used to introduce zeros selectively into a 
matrix. 


C 
C To rotate the first two rows of a matrix and zero 
C out the element in the first column of the second row: 
C 
INTEGER INCX,N 
REAL X(20,20),A,B,C,S 


INCX = 20 
N = 20 

A = X(1,1) 
B = X(2,1) 


CALL BLAS1SVSROTG(A,B,C,S) 
CALL BLAS1SVSROT(N,X,INCX,X(2,1), INCX,C,$) 


RATLI 4°77 


BLAS1$VxROTG 


BLAS1$VxROTG—Generate the Elements for a Givens Plane 


Format 


Returns 


Arguments 


MTH-—17&8 


Rotation 


The Generate the Elements for a Givens Plane Rotation routines construct a 
Givens plane rotation that eliminates the second element of a two-element vector. 


BLAS1$VSROTG a,b,c,s 
BLAS1$VDROTG a,b,c,s 
BLASI$VGROTG a,b,c,s 
BLASI$VCROTG a,b.c,s 
BLAS1$VZROTG a,b,c,s 
BLASI$VWROTG a,b,c,s 


Use BLAS1$VSROTG for single-precision real operations. Use BLAS1$VDROTG 
for double-precision real (D-floating) operations and BLASI$VGROTG for double- 


precision real (G-floating) operations. 


Use BLASI$VCROTG for single-precision complex operations. Use 
BLAS1$VZROTG for double-precision complex (D-floating) operations and 
BLAS1$VWROTG for double-precision complex (G-floating) operations. 


None. 

a 

OpenVMS usage _floating_point or complex_number 

type F_floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access modify 

mechanism by reference 


On entry, first element of the input vector. On exit, rotated element r. The a 
argument is the address of a floating-point or floating-point complex number that 
is this vector element. 


Specify the data type as follows: 


Routine Data Type fora 
BLAS1$VSROTG F-floating real 
BLAS1$VDROTG D-floating real 
BLAS1$VGROTG G-floating real 
BLASI$VCROTG F-floating complex 
BLAS1$VZROTG D-floating complex 
BLAS1$VWROTG G-floating complex 


BLAS1$VxROTG 


b 

OpenVMS usage _ floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
| D_floating, G_floating complex 

access modify 

mechanism by reference 


On entry, second element of the input vector. On exit from BLAS1$VSROTG, 
BLAS1$VDROTG, and BLASI$VGROTG, reconstruction element z. (See the 
Description section for more information about z.) The b argument is the address 
of a floating-point or floating-point complex number that is this vector element. 


Specify the data type as follows: 


Routine Data Type for b 
BLAS1$VSROTG F-floating real 
BLAS1$VDROTG D-floating real 
BLAS1$VGROTG G-floating real 
BLAS1$VCROTG F-floating complex 
BLASI$VZROTG D-floating complex 
BLAS1I$VWROTG G-floating complex 
Cc 

OpenVMS usage _ floating_point 

type F floating, D_floating, or G_floating real 
access write only 

mechanism by reference 


First rotation element, which can be interpreted as the cosine of the angle of 
rotation. The c argument is the address of a floating-point or floating-point 
complex number that is this vector element. 


Specify the data type (which is always real) as follows: 


Routine Data Type for c 

BLAS1$VSROTG and F-floating real 

BLAS1$VCROTG 

BLAS1$VDROTG and D-floating real 

BLAS1$VZROTG 

BLASI$VGROTG and G-floating real 

BLAS1$VWROTG 

S 

OpenVMS usage _ floating_point or complex_number 

type F_floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access write only 

mechanism by reference 


KATLI_1470 


BLAS1$VxROTG 


Description 


KATHW_ARN 


Second rotation element, which can be interpreted as the sine of the angle of 
rotation. The s argument is the address of a floating-point or floating-point 
complex number that is this vector element. 


Specify the data type as follows: 


Routine Data Type for s 
BLAS1$VSROTG F-floating real 
BLAS1$VDROTG D-floating real 
BLAS1$VGROTG _ G-floating real 
BLAS1$VCROTG F-floating complex 
BLAS1$VZROTG D-floating complex 
BLASI$VWROTG G-floating complex 


BLASI$VSROTG, BLASI$VDROTG, and BLAS1$VGROTG construct 

a real Givens plane rotation. BLASI$VCROTG, BLAS1$VZROTG, and 
BLAS1$VWROTG construct a complex Givens plane rotation. The Givens plane 
rotation eliminates the second element of a two-element vector. The elements 
of the vector are real or complex single-precision or double-precision (D and G) 
numbers. The routine name determines the data type you should specify for 
arguments a, b, and s. Specify the same data type for each of these arguments. 


BLAS1$VSROTG, BLAS1$VDROTG, and BLASI$VGROTG can use the 
reconstruction element z to store the rotation elements for future use. There 
is no counterpart to the term z for BLASI$VCROTG, BLASI$VZROTG, and 
BLASI$VWROTG. 


The BLAS1$VxROTG routines can be used to introduce zeros selectively into a 
matrix. 


For BLAS1$VDROTG, BLASI$VGROTG, BLASI$VZROTG, and 
BLAS1$VWROTG (the double-precision routines), the elements of the vector 
are scaled to avoid intermediate overflow or underflow. BLASI$VSROTG and 
BLAS1$VCROTG (the single-precision routines) use a backup data type to avoid 
intermediate underflow or overflow, which may cause the final result to differ 
from the original FORTRAN routine. 


BLAS1$VSROTG, BLAS1$VDROTG, and BLAS1$VGROTG — Real Givens Plane 
Rotation 

Given the elements a and 6 of an input vector, BLASI$VSROTG, and 
BLASI$VDROTG, BLAS1$VGROTG calculate the elements c and s of an 
orthogonal matrix such that: 


Example 


BLAS1$VxROTG 


A real Givens plane rotation is constructed for values a and 8 by computing values 
for r, c, s, and z, as follows: 


r=pvVa“-+ b 
where: 

= SIGN(a) if |a| > [6] 
p = SIGN(8) if |a|<|8| 


c= + if r40 
c=1ifr=0 
s= 4 if r40 
s=Oifr=0 


z=s if |a| > |b 

z=1if |a|<|b| and c40 and r40 

z=1if |a|<|b| and c=0 and r40 

z=Oifr=0 

BLAS1$VSROTG, BLAS1$VDROTG, and BLASI$VGROTG can use the 


reconstruction element z to store the rotation elements for future use. The 
quantities c and s are reconstructed from z as follows: 


For |z| = 1,¢ =0 and s = 1.0 
For |z| < 1,c = V1— 27 ands =z 
For |z| > 1c=tands=V1-c? 


The arguments c and s can be passed to the BLAS1$VxROT routines. 


BLAS1$VCROTG, BLAS1$VZROTG, and BLAS1$VWROTG — Complex Givens 
Plane Rotation | 

Given the elements a and 6 of an input vector, BLASI$VCROTG, 
BLAS1$VZROTG, and BLAS1$VWROTG calculate the elements c and s of an 
orthogonal matrix such that: 


C $y +489] |ayt2*aq| [ry tir*re 
—s, +2* 89 c by titbs | 0 


There are no BLAS Level 1 routines with which you can use complex ec and s 
arguments. 


C 
C To generate the rotation elements for a vector of 
C elements a and b: 
C 
REAL A,B,C,S$ 
CALL SROTG(A,B,C,S) 


MTH-181 


BLAS1$VxSCAL_ 


BLAS1$VxSCAL—Scale the Elements of a Vector 


Format 


Returns 


Arguments 


MTH-182 


The Scale the Elements of a Vector routines compute a « z where a is a scalar 
number and z is an n-element vector. 


BLAS1$VSSCAL na ,x ,incx 
BLASI$VDSCAL _n,a ,x ,incx 
BLASI$VGSCAL _n,a ,x ,incx 
BLASI$VCSCAL _n,a ,x ,incex 
BLAS1$VCSSCAL _n,a ,x ,incx 
BLASI$VZSCAL _n,a ,x ,incx 
BLASI$VWSCAL _n,a ,x ,incx 
BLAS1$VZDSCAL _n,a ,x ,incx 
BLAS1I$VWGSCAL _n,a ,x ,incx 


Use BLAS1$VSSCAL to scale a real single-precision vector by a real single- 
precision scalar. 


Use BLAS1$VDSCAL to scale a real double-precision (D-floating) vector by a 
real double-precision (D-floating) scalar. Use BLASI$VGSCAL to scale a real 
double-precision (G-floating) vector by a real double-precision (G-floating) scalar. 


Use BLAS1$VCSCAL to scale a complex single-precision vector by a complex 
single-precision scalar. Use BLASI$VCSSCAL to scale a complex single-precision 
vector by a real single-precision scalar. 


Use BLASI$VZSCAL to scale a complex double-precision (D-floating) vector 
by a complex double-precision (D-floating) scalar. Use BLAS1I$VWSCAL to 
scale a complex double-precision (G-floating) vector by a complex double- 
precision (G-floating) scalar. Use BLAS1$VZDSCAL to scale a complex double- 
precision (D-floating) vector by a real double-precision (D-floating) scalar. Use 
BLAS1$VWGSCAL to scale a complex double-precision (G-floating) vector by a 
real double-precision (G-floating) scalar. 


None. 

n 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vector z to be scaled. The n argument is the address of a 
signed longword integer containing the number of elements to be scaled. If you 
specify a value for n that is less than or equal to 0, then x is unchanged. 


BLAS1$VxSCAL 


a 

OpenVMS usage _ floating_point or complex_number 

type F floating, D_floating, G_floating real or F_floating, 
| D_floating, G_floating complex 

access read only 

mechanism by reference 


Scalar multiplier for the elements of vector z. The a argument is the address of a — 
floating-point or floating-point complex number that is this multiplier. 


Specify the data type as follows: 


Routine Data Type for a 
BLAS1$VSSCAL and F-floating real 
BLAS1$VCSSCAL 

BLASI$VDSCAL and D-floating real 
BLAS1$VZDSCAL 

BLAS1$VGSCAL and G-floating real 
BLAS1$VWGSCAL | 

BLASI$VCSCAL | F-floating complex 
BLAS1$VZSCAL D-floating complex 
BLAS1$VWSCAL G-floating complex 


If you specify 1.0 for a, then x is unchanged. 


X 

OpenVMS usage _ floating_point or complex_number 

type F' floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access modify 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. On entry, this argument is an array of length at least 


1+ (n— 1) # |inca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


Specify the data type as follows: 


Routine Data Type for x 
BLAS1$VSSCAL F-floating real 
BLAS1$VDSCAL D-floating real 
BLAS1$VGSCAL G-floating real 
BLASI$VCSCAL and F-floating complex 
BLAS1$VCSSCAL 


MTH-183 


BLAS1$VxSCAL 


Description 


MTH-184 


Routine Data Type for x 
BLAS1$VZSCAL and D-floating complex 
BLAS1$VZDSCAL 

BLAS1I$VWSCAL and G-floating complex 
BLAS1$VWGSCAL 


On exit, x is an array of length at least 


1+ (n— 1) * |incz| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


After the call to BLAS1$VxSCAL, z; is replaced by a + z;. If a shares a memory 
location with any element of the vector z, results are unpredictable. 


IncX 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than 0, then z is referenced forward in array x; that is, x; is referenced in: 


z(1+ (2 = 1) *tncz) 


where: 

x = array specified in x 

L = element of the vector z 

incx = increment argument for the array x specified in inex 


If you specify a negative value for inex, it is interpreted as the absolute value of 
incx. If inex equals 0, the results are unpredictable. 


BLAS1$VxSCAL computes a+ where a is a scalar number and z is an n-element 
vector. The computation is expressed as follows: 


LY LY 
«—a 


In Zn 


Vector z contains n elements that are accessed from array x by stepping inex 
elements at a time. The vector z can be a row or a column of a matrix. Both 
forward and backward indexing are permitted. 


The public-domain BLAS Level 1 xSCAL routines require a positive value for 
inex. The Run-Time Library BLAS Level 1 routines interpret a negative value 
for inex as the absolute value of inex. 


The algorithm does not provide a special case for a = 0. Therefore, specifying 
0 for a has the effect of setting to zero all elements of the vector z using vector 
operations. 


Example 


C 


C To scale a vector x by 2.0 using SSCAL: 


C 


INTEGER INCX,N 
REAL X(20),A 

INCX = 1 

A=2 

N = 20 

CALL BLAS1S$VSSCAL(N,A,X, INCX) 


BLAS1$VxSCAL 


MTH-185 


BLAS1$VxSWAP 


BLAS1$VxSWAP—Swap the Elements of Two Vectors 


~ Format 


Returns 


Arguments 


MTH-186 


The Swap the Elements of Two Vectors routines swap n elements of the vector z 
with the vector y. 7 


BLAS1I$VSSWAP _n ,x ,inex ,y ,incy 
BLASI1$VDSWAP _n ,x ,incx ,y ,incy 
BLASI$VCSWAP _n ,x ,incx ,y ,incy 
BLAS1I$VZSWAP _ nx ,incx ,y ,incy 


Use BLAS1$VSSWAP for single-precision real operations and BLAS1$VDSWAP 
for double-precision real (D or G) operations. 


Use BLASI$VCSWAP for single-precision complex operations and 
BLAS1$VZSWAP for double-precision complex (D or G) operations. 


None. 

n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Number of elements in vector z to be swapped. The n argument is the address of 
a signed longword integer containing the number of elements to be swapped. 


X 

OpenVMS usage _ floating_point or complex_number 

type F’ floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access modify 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array x are 
accessed only if the increment argument of x, called inex, is 1. The x argument 
is the address of a floating-point or floating-point complex number that is this 
array. On entry, this argument is an array of length at least 


1+ (n — 1) # |2nca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


BLAS1$VxSWAP 


Specify the data type as follows: 


Routine Data Type for x 

BLAS1$VSSWAP F-floating real 
BLASI$VDSWAP D-floating or G-floating real 
BLAS1$VCSWAP F-floating complex 
BLAS1$VZSWAP D-floating or G-floating complex 


If n is less than or equal to 0, then x and y are unchanged. If any element of z 
shares a memory location with an element of y, the results are unpredictable. 


On exit, x is an array of length at least 


1+ (n— 1) * |enca| 


where: 
n = number of vector elements specified in n 
incx = increment argument for the array x specified in inex 


After the call to BLAS1$VxSWAP, n elements of the array specified by x are 
interchanged with n elements of the array specified by y. 


incx 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array x. The inex argument is the address of a 
signed longword integer containing the increment argument. If inex is greater 
than or equal to 0, then z is referenced forward in array x; that is, 2; is referenced 
in: | 


a(1+ (2 — 1) *2nca) 


where: 

x = array specified in x 

L = element of the vector x 

incx = increment argument for the array x specified in inex 


If inex is less than 0, then z is referenced backward in array x; that is, x; is 
referenced in: 


a(1+ (n — 1) « |enca|) 


where: 

x = array specified in x 

n = number of vector elements specified in n 

l = element of the vector x 

incx = increment argument for the array x specified in inex 


MTH-187 


BLAS1$VxSWAP 


MTH-188 


y 

OpenVMS usage floating_point or complex_number 

type F'_floating, D_floating, G_floating real or F_floating, 
D_floating, G_floating complex 

access modify 

mechanism by reference, array reference 


Array containing the elements to be accessed. All elements of array y are 
accessed only if the increment argument of y, called incy, is 1. The y argument 
is the address of a floating-point or floating-point complex number that is this 
array. On entry, this argument is an array of length at least 


1+ (n — 1) * [ency| 


where: 
n = number of vector elements specified in n 
incy = increment argument for the array y specified in incy 


Specify the data type as follows: 


Routine Data Type for y 
BLAS1$VSSWAP F-floating real 
BLAS1$VDSWAP D-floating or G-floating real 
BLAS1I$VCSWAP F-floating complex 
BLAS1$VZSWAP D-floating or G-floating complex 


If n is less than or equal to 0, then x and y are unchanged. If any element of z 
shares a memory location with an element of y, the results are unpredictable. 


On exit, y is an array of length at least 


1+ (n —1) # |ency| 


where: 
n = number of vector elements specified in n 
incy = increment argument for the array y specified in incy 


After the call to BLAS1$VxSWAP, n elements of the array specified by x are 
interchanged with n elements of the array specified by y. 


incy 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array y. The incy argument is the address of a 
signed longword integer containing the increment argument. If incy is greater 
than or equal to 0, then y is referenced forward in array y; that is, y, is referenced 
In: 


y(1+ (2 — 1) *zncy) 


Description 


Example 


BLAS1$VxSWAP 


where: 

y = array specified in y 

L = element of the vector y 

incy = increment argument for the array y specified in incy 


If incy is less than 0, then y is referenced backward in array y; that is, y; is 
referenced in: 


y(1+ (n — 2) * jency]) 


where: 

y = array specified in y 

n = number of vector elements specified in n 

L = element of the vector y 

incy = increment argument for the array y specified in incy 


BLASI$VSSWAP, BLASI$VDSWAP, BLAS1$VCSWAP, and BLAS1$VZSWAP 
swap n elements of the vector z with the vector y. Vectors z and y contain n 
elements that are accessed from arrays x and y by stepping inex and incy 
elements at a time. Both z and y are real or complex single-precision or double- 
precision (D and G) n-element vectors. The vectors can be rows or columns of a 
matrix. Both forward and backward indexing are permitted. 


You can use the routine BLAS1$VxSWAP to invert the storage of elements of a 
vector within itself. If inex is greater than 0, then z; can be moved from location 


a(1+ (¢-—1) *incz) to 2(1+ (n —2) * inca) 


The following code fragment inverts the storage of elements of a vector within 
itself: 


NN = N/2 
LHALF = 1+(N-NN)*INCX 
CALL BLAS1SVxSWAP(NN,X,INCX,X(LHALF) , -INCX) 


BLASI$VxSWAP does not check for a reserved operand. 


C 
C To swap the contents of vectors x and y: 
C 

INTEGER INCX, INCY,N 

REAL X(20),¥(20) 

INCX = 1] 

INCY = 1 

N = 20 

CALL BLASISVSSWAP(N,X, INCX, Y, INCY) 
C 


C To invert the order of storage of the elements of x within 
C itself; that is, to move x(1l),...,x(100) to x(100),...,x(1): 
C 

INCX = l 

INCY = -l 


CALL BLAS1SVSSWAP(N,X,INCX,X(51), INCY) 


MTH-—189 


MTH$VxFOLRy_MA_V15 


MTHS$VxFOLRy_MA_V15—First Order Linear Recurrence — 


Format 


Returns 


Arguments 


MTH-—190 


Multiplication and Addition 


The First Order Linear Recurrence — Multiplication and Addition routines 
provide a vectorized algorithm for the linear recurrence relation that includes 
both multiplication and addition operations. 


MTH$VJFOLRP_MA_V15__ n,a,inca,b,incb,c,incc 
MTH$VFFOLRP_MA_V15__n,a,inca,b,incb,c,incc 
MTH$VDFOLRP_MA_V15__n,a,inca,b,incb,c,incc 
MTH$VGFOLRP_MA_V15 _n,a,inca,b,incb,c,incc 
MTH$VJFOLRN_MA_V15__n,a,inca,b,incb,c,ince 
MTH$VFFOLRN_MA_V15_n,a,inca,b,incb,c,incc 
MTH$VDFOLRN_MA_V15__ n,a,inca,b,incb,c,incc 
MTHS$VGFOLRN_MA_V15__n,a,inca,b,incb,c,incc 


To obtain one of the preceding formats, substitute the following for x and y in 
MTH$VxFOLRy_MA_V15: 


x = _ J for longword integer, F for F-floating, D for D-floating, G for G-floating 
y = P fora positive recursion element, N for a negative recursion element 
None. 

n 

OpenVMS usage  longword_signed 

type longword integer (signed) 

access read only 

mechanism by reference 


Length of the linear recurrence. The n argument is the address of a signed 
longword integer containing the length. 


a 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access read only 

mechanism by reference, array reference 


Array of length at least 
1+ (n— 1) *inca 
where: 


n = length of the linear recurrence specified in n 


MTH$VxFOLRy_MA_V15 


inca = increment argument for the array a specified in inca 


The a argument is the address of a longword integer or floating-point that is this 
array. 


inca 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array a. The inca argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for inca. 


b 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access read only | 

mechanism by reference, array reference 


Array of length at least 
1+ (n —1) *incb 


where: 
n = length of the linear recurrence specified in n 
incb = increment argument for the array b specified in incb 


The b argument is the address of a longword integer or floating-point number 
that is this array. 


incb 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array b. The incb argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for incb. 


Cc 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access modify : 

mechanism by reference, array reference 


Array of length at least 


1+nx*ince 


where: 
n = length of the linear recurrence specified in n 
ince = increment argument for the array c specified in ince 


The ¢ argument is the address of a longword integer or floating-point number 
that is this array. 


KATH_1Q04 


MTH$VxFOLRy_MA_V15 


Description 


MTH-192 


ince 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array c. The inec argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for inee. Do not specify 0 for ince. 


MTH$VxFOLRy_MA_V15 is a group of routines that provides a vectorized 
algorithm for computing the following linear recurrence relation: 


C(f+1) =+/-C(J) « A(I) + Bi) 


Note 


Save the contents of vector registers VO through V15 before you call this 
routine. 


Call this routine to utilize vector hardware when computing the recurrence. As 
an example, the call from VAX FORTRAN is as follows: 


Kl 
K2 
K3 


MTHSVxFOLRy MA V15(N,A(K1) ,INCA,B(K2) , INCB,C(K3) , INCC) 
The preceding FORTRAN call replaces the following loop: 


: 


A 
NO 
ueoue tl 


=1,N 
C(K3+I*INCC) = {+/-}C(K3+(I-1)*INCC) * A(K1+(I-1)*INCA) 
+ B(K2+(I-1) *INCB) 


oO 
oO 
Hi 


ENDDO 


The arrays used in a FOLR expression must be of the same data type in order to 
be vectorized and user callable. The MTH$ FOLR routines assume that all of the 
arrays are of the same data type. 


This group of routines, MTH$VxFOLRy_MA_V15 (and also MTH$VxFOLRy_ 
z_V8) save the result of each iteration of the linear recurrence relation in an 
array. This is different from the behavior of MTH$VxFOLRLy_MA_V5 and 
MTH$VxFOLRLy_z_V2, which return only the result of the last iteration of the 
linear recurrence relation. 


For the output array (c), the increment argument (ince) cannot be 0. However, 
you can specify 0 for the input increment arguments (inca and incb). In that 
case, the input will be treated as a scalar value and broadcast to a vector input 
with all vector elements equal to the scalar value. 


In MTH$VxFOLRy_MA_V15, array ec can overlap array a and array b, or both, 
as long as the address of array element c, is not also the address of an element 
of a or b that will be referenced at a future time in the recurrence relation. For 
example, in the following code fragment you must ensure that the address of 
c(1+2*zncc) does not equal the address of either a(j * inca) or 6(k * zncb) for 


Examples 


MTH$VxFOLRy_MA_V15 


1<i<n and j>2 +1. 


DO I = 1,N 
~C(1+I*INCC) = C(1+(I-1)*INCC) * A(1+(I-1)*INCA) + B(1+(I-1)*INCB) 
ENDDO 
1. -& 
C The following FORTRAN loop computes 
C a linear recurrence. 
C 
INTEGER I 
DIMENSION A(200), B(50), C(50) 
EQUIVALENCE (B,C) 
CA = ates 
DO I= 5, 50 | 
C(I) = C((I-1)) * A(I*3) + B(T) 
ENDDO 
C 
€ The following call from FORTRAN to a FOLR 
C routine replaces the preceding loop. 
C 
DIMENSION A(200), B(50), C(50) 
EQUIVALENCE (B,C) 
C(4) Scan 
CALL MTHSVFFOLRP_MA V15(46, A(15), 3, B(5), 1, C(4), 1) 
2. C 
C The following FORTRAN loop computes 
C a linear recurrence. 
C 
INTEGER K,N, INCA, INCB,INCC,I 
DIMENSION A(30), B(6), C(50) 
K = 44 
N = 6 
INCA = 5 
INCB = 1 
INCC = 1 
DO I=1,N 
C(K+I*INCC) = -C(K+(I-1)*INCC) * A(I*INCA) + B(I*INCB) 
ENDDO 
C 
C The following call from FORTRAN to a FOLR 
C routine replaces the preceding loop. 
C 


INTEGER K,N, INCA, INCB, INCC 
DIMENSION A(30), B(6), C(50) 
K = 44 

N = 6 
INCA 
INCB 
INCC = 1 

CALL MTHSVFFOLRN MA V15(N, A(INCA), INCA, B(INCB), INCB, C(K), INCC) 


5 
] 


MTH$VxFOLRy_z_V8 


MTH$VxFOLRy_z_V8—First Order Linear Recurrence — 
Multiplication or Addition 


The First Order Linear Recurrence — Multiplication or Addition routines provide 
a vectorized algorithm for the linear recurrence relation that includes either a 
multiplication or an addition operation, but not both. 
Format 
MTH$VJFOLRP_M_V8 __n,a,inca,b,incb 
MTH$VFFOLRP_M_V8 _n,a,inca,b,incb 
MTH$VDFOLRP_M_V8 _n,a,inca,b,incb 
MTH$VGFOLRP_M_V8 _n,a,inca,b,incb 
MTH$VJFOLRN_M_V8 _ n,a,inca,b,incb 
MTH$VFFOLRN_M_V8 _n,a,inca,b,incb 
MTH$VDFOLRN_M_V8_n,a,inca,b,incb 
MTHSVGFOLRN_M_V8_n,a,inca,b,incb 
MTH$VJFOLRP_A_V8 __n,a,inca,b,incb 
MTH$VFFOLRP_A_V8 _n,a,inca,b,incb 
MTHS$VDFOLRP_A_V8 __n,a,inca,b,incb 
MTH$VGFOLRP_A_V8 __n,a,inca,b,incb 
MTH$VJFOLRN_A_V8__ n,a,inca,b,incb 
MTH$VFFOLRN_A_V8 _ n,a,inca,b,incb 
MTH$VDFOLRN_A_V8 _n,a,inca,b,incb 
MTH$VGFOLRN_A_V8 __n,a,inca,b,incb 


To obtain one of the preceding formats, substitute the following for x, y, and z in 
MTH$VxFOLRy_z_V8: 


= J for longword integer, F for F-floating, D for D-floating, G for G-floating 
= P for a positive recursion element, N for a negative recursion element 
z =~ M for multiplication, A for addition 


Returns 


None. 


Arguments 


n | 
OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Length of the linear recurrence. The n argument is the address of a signed 
longword integer containing the length. 


AATHI_1QA 


MTHS$VxFOLRy_z_V8 


a 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access read only 

mechanism by reference, array reference 


Array of length at least 
1+(n—1)*inca 


where: 
n = length of the linear recurrence specified in n 
inca = increment argument for the array a specified in inca 


The a argument is the address of a longword integer or floating-point that is this 
array. : 


inca 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array a. The inca argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for inca. 


b 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access modify 

mechanism by reference, array reference 


Array of length at least 
1+ (n— 1) *incb 


where: 
n = length of the linear recurrence specified in n 
incb = increment argument for the array b specified in ineb 


The b argument is the address of a longword integer or floating-point number 
that is this array. 


incb 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array b. The incb argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for incb. 


RATLI ANCL 


MTHS$SVxFOLRy_z_V8_ 


Description 


AATLI 408 


MTH$VxFOLRy_z_V8 is a group of routines that provide a vectorized algorithm 
for computing one of the following linear recurrence relations: 


B(I) = +/-B(I - 1) * A(J) 

or 

B(I) = +/-B(U - 1) + A(J) 

For the first relation, specify M for z in the routine name to denote multiplication; 

for the second relation, specify A for z in the routine name to denote addition. 
Note 


Save the contents of vector registers VO through V8 before you call this 
routine. 


Call this routine to utilize vector hardware when computing the recurrence. As 
an example, the call from VAX FORTRAN is as follows: 


CALL MTHSVxFOLRy z V8(N,A(K1),INCA,B(K2) , INCB) 
The preceding FORTRAN call replaces the following loop: 


Kl 
RDS st 
pI=1, N 

B(K2+I*INCB) = {+/-}B(K2+(I-1)*INCB) {+/*} A(K1+(I-1)*INCA) 
ENDDO 


The arrays used in a FOLR expression must be of the same data type in order to 
be vectorized and user callable. The MTH$ FOLR routines assume that all of the 
arrays are of the same data type. | 


This group of routines, MTH$VxFOLRy_z_V8 (and also MTH$VxFOLRy_MA_ 
V15) save the result of each iteration of the linear recurrence relation in an 
array. This is different from the behavior of MTH$VxFOLRLy_MA_V5 and 
MTH$VxFOLRLy_z_V2, which return only the result of the last iteration of the 
linear recurrence relation. 


For the output array (b), the increment argument (incb) cannot be 0. However, 
you can specify 0 for the input increment argument (inca). In that case, the 
input will be treated as a scalar and broadcast to a vector input with all vector 
elements equal to the scalar value. 


Examples 


AAAMRA AAANANQD QAAaAAQD 


QaARANQ 


MTH$VxFOLRy_z V8 


The following FORTRAN loop computes 
a linear recurrence. 


D FLOAT 
INTEGER N, INCA, INCB,I 
DIMENSION A(30), B(13) 
N = 6 
INCA = 5 
INCB = 2 
DOI=1, N 
B(1+I*INCB) = -B(1+(I-1)*INCB) * A(I*INCA) 
ENDDO 


ton ol 


The following call from FORTRAN to a FOLR 
routine replaces the preceding loop. 


D FLOAT 
INTEGER N, INCA, INCB 
REAL*8 A(30), B(13) 
N = 6 


INCA = 5 
INCB = 2 
CALL MTHSVDFOLRN M V8(N, A(INCA), INCA, B(1), INCB) 


The following FORTRAN loop computes 
a linear recurrence. 


G FLOAT 
INTEGER N, INCA, INCB 
DIMENSION A(30), B(13) 
N= 5 
INCA = 5 
INCB = 2 
DO I = 2, N 
B(1+I*INCB) = B((I-1)*INCB) + A(I*INCA) 
ENDDO 


The following call from FORTRAN to a FOLR 
routine replaces the preceding loop. 


G FLOAT 
INTEGER N, INCA, INCB 
REAL*8 A(30), B(13) 


INCA = 5 
INCB = 2 
CALL MTH$VGFOLRP A V8(N, A(INCA), INCA, B(INCB), INCB) 


RATLI 407 


MTH$VxFOLRLy_MA_V5 


MTH$VxFOLRLy_MA_V5—First Order Linear Recurrence — 


Format 


Returns 


Arguments 


hMATH—19R 


Multiplication and Addition — Last Value 


The First Order Linear Recurrence — Multiplication and Addition — Last 
Value routines provide a vectorized algorithm for the linear recurrence relation 
that includes both multiplication and addition operations. Only the last value 
computed is stored. 


MTH$VJFOLRLP_MA_V5 _ n,a,inca,b,incb,t 
MTH$VFFOLRLP_MA_V5 _ n,a,inca,b,incb,t 
MTH$VDFOLRLP_MA_V5_n,a,inca,b,incb,t 
MTH$VGFOLRLP_MA_V5 _ n,a,inca,b,incb,t 
MTH$VJFOLRLN_MA_V5_ n,a,inca,b,incb,t 
MTH$VFFOLRLN_MA_V5 _n,a,inca,b,incb,t 
MTH$VDFOLRLN_MA_V5_n,a,inca,b,incb,t 
MTH$VGFOLRLN_MA_V5 _ n,a,inca,b,incb,t 


To obtain one of the preceding formats, substitute the following for x and y in 
MTH$VxFOLRLy_MA_V5: 


J for longword integer, F for F-floating, D for D-floating, G for G-floating 
P for a positive recursion element, N for a negative recursion element 


OpenVMS usage longword_signed or floating_point 


type longword integer (signed), F_floating, D_floating or G_floating 
access write only 
mechanism by value 


The function value is the result of the last iteration of the linear recurrence 
relation. The function value is returned in RO or RO and RI. 


n 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Length of the linear recurrence. The n argument is the address of a signed 
longword integer containing the length. 


a 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access read only | 

mechanism by reference, array reference 


MTH$VxFOLRLy_MA_V5 


Array of length at least 

1+ (n—1) *tnca 

where: 

n = length of the linear recurrence specified in n 

inca = increment argument for the array a specified in inca 


The a argument is the address of a longword integer or floating-point that is this 
array. : 


inca 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array a. The inca argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for inca. 


b 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access read only 

mechanism by reference, array reference 


Array of length at least 
1+ (n—1) «inch 


where: 
n = length of the linear recurrence specified in n 
incb = increment argument for the array b specified in incb 


The b argument is the address of a longword integer or floating-point number 
that is this array. 


incb 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array b. The incb argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for incb. 


t 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating - 
access modify 

mechanism by reference 


Variable containing the starting value for the recurrence; overwritten with the 
value computed by the last iteration of the linear recurrence relation. The t 
argument is the address of a longword integer or floating-point number that is 
this value. 


MTH-199 


MTH$VxFOLRLy_MA_V5 


Description 


Examples 


MTH-200 


MTH$VxFOLRLy_MA_V5 is a group of routines that provide a vectorized 
algorithm for computing the following linear recurrence relation. (The T on the 
right side of the equation is the result of the previous iteration of the loop.) 


T = +/-T* A(1) + B(D) 


Note 


Save the contents of vector registers VO through V5 before you call this 
routine. 


Call this routine to utilize vector hardware when computing the recurrence. As 
an example, the call from VAX FORTRAN is as follows: 


CALL MTH$VxFOLRy MA V5(N,A(K1),INCA,B(K2),INCB,T) 
The preceding FORTRAN call replaces the following loop: 


A 
No 
nou 


DOI=1,N 
T = {+/-}T * A(K1+(I-1)*INCA) + B(K1+(I-1)*INCB) 
ENDDO 


The arrays used in a FOLR expression must be of the same data type in order to 
be vectorized and user callable. The MTH$ FOLR routines assume that all of the 
arrays are of the same data type. 


This group of routines, MTH$VxFOLRLy_MA_V5 (and also MTH$VxFOLRLy_ 
z_V2) returns only the result of the last iteration of the linear recurrence 
relation. This is different from the behavior of MTH$VxFOLRy_MA_V15 (and 
also MTH$VxFOLRy_z_V8), which save the result of each iteration of the linear 
recurrence relation in an array. 


If you specify 0 for the input increment arguments (inca and ineb), the input will 
be treated as a scalar and broadcast to a vector input with all vector elements 
equal to the scalar value. 


The following FORTRAN loop computes 
a linear recurrence. 


Mla AANA 


G FLOAT 
INTEGER N, INCA, INCB,I 
REAL*8 A(30), B(6), T 


INCA = 5 
INCB = 1 
= 78.9847562 
DO Sb N 
T = -T * A(I*INCA) + B(I*INCB) 
ENDDO 


AAaAAANA 


AAAAN 


lQnhraAaan 


MTH$VxFOLRLy_MA_V5 


The following call from FORTRAN to a FOLR 
routine replaces the preceding loop. 


G FLOAT 

INTEGER N, INCA, INCB 

DIMENSION A(30), B(6), T 

N = 6 

INCA = 5 

INCB = 1 

T = 78.9847562 

T = MTHSVGFOLRLN MA V5(N, A(INCA), INCA, B(INCB), INCB, T) 


The following FORTRAN loop computes 
a linear recurrence. 


G FLOAT 
INTEGER N, INCA, INCB,I 
REAL*8 A(30), B(6), T 


N= 6 

INCA = 5 

INCB = 1 

T = 78.9847562 

DI=1,N 

T = T * A(I*INCA) + B(I*INCB) 
ENDDO 


The following call from FORTRAN to a FOLR 
routine replaces the preceding loop. 


G FLOAT 

INTEGER N, INCA, INCB 

DIMENSION A(30), B(6), T 

N= 6 

INCA = 5 

INCB = 1 

T = 78.9847562 

T = MTH$VGFOLRLP MA V5(N, A(INCA), INCA, B(INCB), INCB, T) 


MTH-201 


MTH$VxFOLRLy_z V2 


MTH$VxFOLRLy_z _V2—First Order Linear Recurrence — 
Multiplication or Addition — Last Value 


Format 


Returns 


MTH-202 


The First Order Linear Recurrence — Multiplication or Addition — Last Value 
routines provide a vectorized algorithm for the linear recurrence relation that 
includes either a multiplication or an addition operation. Only the last value 


computed is stored. 


MTH$VJFOLRLP_M_V2 
MTH$VFFOLRLP_M_V2 
MTH$VDFOLRLP_M_V2 
MTH$VGFOLRLP_M_V2 
MTH$VJFOLRLN_M_V2 
MTH$VFFOLRLN_M_V2 
MTH$VDFOLRLN_M_V2 
MTH$VGFOLRLN_M_V2 
MTH$VJFOLRLP_A_V2 
MTH$VFFOLRLP_A_V2 
MTH$VDFOLRLP_A_V2 
MTH$VGFOLRLP_A_V2 
MTH$VJFOLRLN_A_V2 
MTH$VFFOLRLN_A_V2 
MTH$VDFOLRLN_A_V2 
MTH$VGFOLRLN_A_V2 


n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 
n,a,inca,t 


n,a,inca,t 


To obtain one of the preceding formats, substitute the following for x, y, and z in 


MTH$VxFOLRLy_z_V2: 


X 


NOS 
I 


J for longword integer, F for F-floating, D for D-floating, G for G-floating 
P for a positive recursion element, N for a negative recursion element 
M for multiplication, A for addition 


OpenVMS usage longword_signed or floating_point 


type longword integer (signed), F_floating, D_floating or G_floating 
access write only 
mechanism by value 


The function value is the result of the last iteration of the linear recurrence 
relation. The function value is returned in RO or RO and Rl. 


Arguments 


MTH$VxFOLRLy_z V2 


n 

OpenVMS usage  longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Length of the linear recurrence. The n argument is the address of a signed 
longword integer containing the length. 


a 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access read only 

mechanism by reference, array reference 


Array of length at least 


n*xinca 

where: 

n = length of the linear recurrence specified in n 

inca = increment argument for the array a specified in inca 


The a argument is the address of a longword integer or floating-point that is this 
array. 


inca 

OpenVMS usage longword_signed 

type longword integer (signed) 
access read only 

mechanism by reference 


Increment argument for the array a. The inca argument is the address of a 
signed longword integer containing the increment argument. For contiguous 
elements, specify 1 for inca. 


t 

OpenVMS usage longword_signed or floating_point 

type longword integer (signed), F_floating, D_floating, or G_floating 
access modify 

mechanism by reference 


Variable containing the starting value for the recurrence; overwritten with the 
value computed by the last iteration of the linear recurrence relation. The t 
argument is the address of a longword integer or floating-point number that is 
this value. 


MTH$VxFOLRLy_z V2 


Description 


MTH$VxFOLRLy_z_V2 is a group of routines that provide a vectorized algorithm 
for computing one of the following linear recurrence relations. (The T on the right 
side of the following equations is the result of the previous iteration of the loop.) 


T=+/-T* A(J) 

or 

T=+/-T+ A(J) 

For the first relation, specify M for z in the routine name to denote multiplication; 

for the second relation, specify A for z in the routine name to denote addition. 
Note 


Save the contents of vector registers VO, V1, and V2 before you call this 
routine. 


Call this routine to utilize vector hardware when computing the recurrence. As 
an example, the call from VAX FORTRAN is as follows: 


CALL MTHS$VxFOLRLy z V2 (N,A(K1),INCA,T) 
The preceding FORTRAN call replaces the following loop: 


Kl = woe. 

DOI=1, N 

T = {+/-}T {+/*} A(K1+(I-1)*INCA) 
ENDDO 


The arrays used in a FOLR expression must be of the same data type in order to 
be vectorized and user callable. The MTH$ FOLR routines assume that all of the 
arrays are of the same data type. 


This group of routines, MTH$VxFOLRLy_z_V2 (and also MTH$VxFOLRLy_ 
MA_V5) return only the result of the last iteration of the linear recurrence 
relation. This is different from the behavior of MTH$VxFOLRy_MA_V15 (and 
also MTH$VxFOLRy_z_V8), which save the result of each iteration of the linear 
recurrence relation in an array. 


If you specify 0 for the input increment argument (inca), the input will be treated 
as a scalar and broadcast to a vector input with all vector elements equal to the 
scalar value. 


Examples 


AAQAAN AAAARAQNA AAAAQ 


AAAANQ 


MTHS$VxFOLRLy_z V2 


The following FORTRAN loop computes 
a linear recurrence. 


D FLOAT 
INTEGER I,N 
REAL*8 A(200), T 
T = 78.9847562 

N = 20 

DOI= 4, N 

T = -T * A(I*10) 
ENDDO 


The following call from FORTRAN to a FOLR 
routine replaces the preceding loop. 


D FLOAT 
INTEGER N 

REAL*8 A(200), T 

T = 78.9847562 

N = 20 

T = MTH$VDFOLRLN M V2(N-3, A(40), 10, T) 


The following FORTRAN loop computes 
a linear recurrence. 


D FLOAT 
INTEGER I,N 
REAL*8 A(200), T 
T = 78.9847562 

N = 20 


DOI = 4, N 
T = T + A(I*10) 
ENDDO 


The following call from FORTRAN to a FOLR 
routine replaces the preceding loop. 


D FLOAT 

INTEGER N 

REAL*8 A(200), T 

T = 78.9847562 

N = 20 

T = MTHSVDFOLRLP A V2(N-3, A(40), 10, T) 


A 


Additional MTHS$ Routines 


The following supported MTH$ routines are not included with the routines in 
the Scalar MTH$ Reference Section because they are rarely used. The majority 
of these routines serve to satisfy external references when intrinsic functions 
in FORTRAN and other languages are passed as parameters. Otherwise, the 
functions are performed by inline code. 


Table A-1 lists all of the entry point and argument information for the MTH$ 
routines not documented in the Scalar MTH$ Reference Section of this manual. 


Table A-1 Additional MTH$ Routines 


Routine Name 


MTH$ABS 


MTH$DABS 


MTH$GABS 


MTH$HABS 


Format: 
Returns: 
f-floating: 


Format: 


Returns: 


d-floating: 


Format: 


Returns: 


g-floating: 


Format: 
Returns: 


h-abs-val: 


h-floating: 


Entry Point Information 


F-floating Absolute Value Routine 

MTHSABS f-floating 

floating_point, F_floating, write only, by value 
floating_point, F_floating, read only, by reference 


D-floating Absolute Value Routine 

MTHS$DABS d-floating 

floating_point, D_floating, write only, by value 
floating_point, D_floating, read only, by reference 


G-floating Absolute Value Routine 

MTHS$GABS ¢g-floating 

floating_point, G_floating, write only, by value 
floating_point, G_floating, read only, by reference 


H-floating Absolute Value Routine 
MTH$HABS h-abs-val, h-floating 
None 


floating point, H_floating, write only, by 
reference 


floating point, H_floating, read only, by 
reference 
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Table A-1 (Cont.) Additional MTH$ Routines 


Routine Name 


MTH$IIABS 


MTH$JIABS 


MTH$IIAND 


MTH$JIAND 


MTH$DBLE 


MTH$GDBLE 


Format: 
Returns: 


word: 


Format: 


Returns: 


longword: 


Format: 


Returns: 
wordl: 


word?: 


Format: 


Returns: 


longword1: 


longword2: 


Format: 
Returns: 


f-floating: 


Format: 
Returns: 


f-floating: 


Entry Point Information 


Word Absolute Value Routine 
MTHS$IIABS word 
word_signed, word (signed), write only, by value 


word_signed, word (signed), read only, by 
reference 


Longword Absolute Value Routine 
MTH$JIABS longword 


longword_signed, longword (signed), write only, 
by value 


longword_signed, longword (signed), read only, 
by reference 


Bitwise AND of Two Word Parameters Routine 
MTH$IIAND word1, word2 


word_unsigned, word (unsigned), write only, by 
value 


word_unsigned, word (unsigned), read only, by 
reference 


word_unsigned, word (unsigned), read only, by 
reference 


Bitwise AND of Two Longword Parameters 
Routine 


MTH$JIAND longword1, longword2 


longword_unsigned, longword (unsigned), write 
only, by value 


longword_unsigned, longword (unsigned), read 
only, by reference 


longword_unsigned, longword (unsigned), read 
only, by reference 


Convert F-floating to D-floating (Exact) Routine 
MTHS$DBLE f-floating 
floating_point, D_floating, write only, by value 


floating_point, F_floating, read only, by reference 


Convert F-floating to G-floating (Exact) Routine 
MTH$GDBLE f-floating 
floating_point, G_floating, write only, by value 


floating_point, F_floating, read only, by reference 
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Table A—1 (Cont.) Additional MTH$ Routines 


Routine Name 


MTH$DIM 


MTH$DDIM 


MTH$GDIM 


MTH$HDIM 


MTH$IIDIM 


Format: 
Returns: 
f-floating1: 
f-floating2: 


Format: 


Returns: 


d-floating1: 
d-floating2: 


Format: 


Returns: 


g-floating1: 
g-floating2: 


Format: 
Returns: 


h-floating: 


h-floating1: 


h-floating2: 


Format: 
Returns: 


wordl: 


word2: 


Entry Point Information 


Positive Difference of Two F-floating Parameters 
Routine 


MTHS$DIM f-floating1, f-floating2 
floating_point, F_floating, write only, by value 
floating_point, F_floating, read only, by reference 


floating _point, F_floating, read only, by reference 


Positive Difference of Two D-floating Parameters 
Routine | 


MTHS$DDIM d-floating1, d-floating2 
floating_point, D_floating, write only, by value 
floating_point, D_floating, read only, by reference 


floating_point, D_floating, read only, by reference 


Positive Difference of Two G-floating Parameters 
Routine 


MTH$GDIM ¢-floating1, g-floating2 
floating_point, G_floating, write only, by value 
floating_point, G_floating, read only, by reference 


floating_point, G_floating, read only, by reference 


Positive Difference of Two H-floating Parameters 
Routine 


MTH$HDIM b-floating, h-floating1, h-floating2 
None 


floating_point, H_floating, write only, by 
reference 


floating_point, H_floating, read only, by 
reference 


floating_point, H_floating, read only, by 
reference 


Positive Difference of Two Word Parameters 
Routine 


MTHS$IIDIM word1, word2 
word_signed, word (signed), write only, by value 


word_signed, word (signed), read only, by 
reference 


word_signed, word (signed), read only, by 
reference 
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Table A-1 (Cont.) Additional MTH$ Routines 


Routine Name 


MTH$JIDIM 


MTH$IIEOR 


MTH$JIEOR 


MTH$IIFIX 


MTH$JIFIX 


Format: 


Returns: 
longword1: 


longword2: 


Format: 


Returns: 
wordl: 


word2: 


Format: 
Returns: 


longword1: 


longword2: 


Format: 
Returns: 
f-floating: 


Format: 


Returns: 


f-floating: 


- Entry Point Information 


Positive Difference of Two Longword Parameters 
Routine 


MTH$JIDIM longword1, longword2 


longword_signed, longword (signed), write only, 
by value 


longword_signed, longword (signed), read only, 
by reference 


longword_signed, longword (signed), read only, 
by reference 


Bitwise Exclusive OR of Two Word Parameters 
Routine 


MTHSITEOR word1, word2 


word_unsigned, word (unsigned), write only, by 
value 


word_unsigned, word (unsigned), read only, by 
reference 


word_unsigned, word (unsigned), read only, by 
reference 


Bitwise Exclusive OR of Two Longword 
Parameters Routine. 


MTHS$JIEOR longword1, longword2 


longword_unsigned, longword (unsigned), write 
only, by value 


longword_unsigned, longword (unsigned), read 
only, by reference 


longword_unsigned, longword (unsigned), read 
only, by reference 


Convert F-floating to Word (Truncated) Routine 
MTHSIIFIX f-floating 

word_signed, word (signed), write only, by value 
floating_point, F_floating, read only, by reference 


Convert F-floating to Longword (Truncated) 
Routine 


MTHS$JIFIX f-floating 


longword_signed, longword (signed), write only, 
by value 


floating point, F_floating, read only, by reference 
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Table A-—1 (Cont.) Additional MTH$ Routines 


Routine Name 


MTH$FLOATI 


MTH$DFLOTI 


MTH$GFLOTI 


MTH$FLOATIJ 


MTH$DFLOTJ 


MTH$GFLOTJ 


Format: 
Returns: 


word: 


Format: 
Returns: 


word: 


Format: 
Returns: 


word: 


Format: 


Returns: 


longword: 


Format: 


Returns: 


longword: 


Format: 


Returns: 


longword: 


Entry Point Information 


Convert Word to F-floating (Exact) Routine 
MTHS$FLOATI word 
floating point, F_floating, write only, by value 


word_signed, word (signed), read only, by 
reference 


Convert Word to D-floating (Exact) Routine 
MTH$DFLOTI word 
floating_point, D_floating, write only, by value 


word_signed, word (signed), read only, by 
reference 


Convert Word to G-floating (Exact) Routine 
MTH$GFLOTI word 
floating point, G_floating, write only, by value 


word_signed, word (signed), read only, by 
reference 


Convert Longword to F-floating (Rounded) 
Routine 


MTH$FLOATJ longword 
floating point, F_floating, write only, by value 


longword_signed, longword (signed), read only, 
by reference 


Convert Longword to D-floating (Exact) Routine 
MTH$DFLOTJ longword 
floating_point, D_floating, write only, by value 


longword_signed, longword (signed), read only, 
by reference 


Convert Longword to G-floating (Exact) Routine 
MTH$GFLOTJ longword 
floating point, G_floating, write only, by value 


longword_signed, longword (signed), read only, 
by reference 
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Table A-1 (Cont.) Additional MTH$ Routines 


Routine Name Entry Point Information 


MTH$FLOOR Convert F-floating to Greatest F-floating Integer 
Routine 
Format: MTH$FLOOR f-floating 
JSB: MTHS$FLOOR_R1 f-floating 
Returns: floating _point, F_floating, write only, by value 
f-floating: floating_point, F_floating, read only, by reference 
MTH$DFLOOR Convert D-floating to Greatest D-floating Integer 
Routine 
Format: MTHS$DFLOOR d-floating 
JSB: MTH$DFLOOR_R3 d-floating 
Returns: floating_point, D_floating, write only, by value 
d-floating: floating_point, D_floating, read only, by reference 
MTH$GFLOOR Convert G-floating to Greatest G-floating Integer 
Routine 
Format: MTH$GFLOOR ¢-floating 
JSB: MTH$GFLOOR_R3 g-floating 
Returns: floating_point, G_floating, write only, by value 
g-floating: floating_point, G_floating, read only, by reference 
MTH$HFLOOR Convert H-floating to Greatest H-floating Integer 
Routine 
Format: MTHS$HFLOOR max-b-float, h-floating 
JSB: MTHS$HFLOOR_R7 h-floating 
Returns: None 
max-h-float: floating_point, H_floating, write only, by 
reference 
h-floating: floating point, H_floating, read only, by 
reference 7 
MTH$AINT Convert F-floating to Truncated F-floating 
Routine 
Format: MTHSAINT f-floating 
JSB: MTHS$AINT_R2 f-floating 
Returns: floating point, F_floating, write only, by value 
f-floating: floating_point, F_floating, read only, by reference 
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Routine Name 


MTH$DINT 


MTH$IIDINT - 


MTH$JIDINT 


MTH$GINT 


MTH$IIGINT 


MTH$JIGINT 


Format: 
JSB: 


Returns: 


d-floating: 


Format: 


Returns: 


d-floating: 


Format: 


Returns: 


d-floating: 


Format: 
JSB: 


Returns: 


g-floating: 


Format: 


Returns: 


g-floating: 


Format: 


Returns: 


g-floating: 


Entry Point Information 


Convert D-floating to Truncated D-floating 
Routine 


MTH$DINT d-fioating 
MTHS$DINT_R4 d-floating 
floating_point, D_floating, write only, by value 


floating_point, D_floating, read only, by reference 


Convert D-floating to Word (Truncated) Routine 
MTHS$IIDINT d-floating 
word_signed, word (signed), write only, by value 


floating_point, D_floating, read only, by reference 


Convert D-floating to Longword (Truncated) 
Routine 


MTH$JIDINT d-floating 


longword_signed, longword (signed), write only, 
by value 


floating_point, D_floating, read only, by reference 


Convert G-floating to Truncated G-floating 
Routine 


MTHS$GINT ¢g-floating 
MTH$GINT_R4 g-floating 
floating_point, G_floating, write only, by value 


floating _point, G_floating, read only, by reference 


Convert G-floating to Word (Truncated) Routine 
MTHSIIGINT g-floating 
word_signed, word (signed), write only, by value 


floating_point, G_floating, read only, by reference 


Convert G-floating to Longword (Truncated) 
Routine 


MTHSJIGINT g-floating 


longword_signed, longword (signed), write only, 
by value 


floating_point, G_floating, read only, by reference 
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Routine Name Entry Point Information 


MTHS$HINT Convert H-floating to Truncated H-floating 
Routine 
Format: MTH$HINT trunc-h-fit, h-floating 
JSB: MTH$HINT_R8 h-floating 
Returns: None 
trunc-h-fit: floating_point, H_floating, write only, by 
reference 
h-floating: floating_point, H_floating, read only, by 
reference 
MTH$IIHINT Convert H-floating to Word (Truncated) Routine 
Format: MTHS$ITHINT bh-floating 
Returns: word_signed, word (signed), write only, by value 
h-floating: floating_point, H_floating, read only, by 
reference 
MTH$JIHINT Convert H-floating to Longword (Truncated) 
Routine 
Format: MTH$JIHINT h-floating 
Returns: longword_signed, longword (signed), write only, 
by value 
h-floating: floating_point, H_floating, read only, by 
reference 
MTH$IINT Convert F-floating to Word (Truncated) Routine 
Format: MTHSIINT f-floating 
Returns: word_signed, word (signed), write only, by value 
f-floating: floating_point, F_floating, read only, by reference 
MTH$JINT Convert F-floating to Longword (Truncated) 
Routine 
Format: MTHSJINT f-floating 
Returns: longword_signed, longword (signed), write only, 
by value 
f-floating: floating_point, F_floating, read only, by reference 
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- Table A-1 (Cont.) Additional MTH$ Routines 


Routine Name Entry Point Information 


MTH$IIOR Bitwise Inclusive OR of Two Word Parameters 
Routine 
Format: MTHSITIOR word1, word2 
Returns: word_unsigned, word (unsigned), write only, by 
value 
wordl: word_unsigned, word (unsigned), read only, by 
reference 
word2: word_unsigned, word (unsigned), read only, by 
reference 
MTH$JIOR Bitwise Inclusive OR of Two Longword 
Parameters Routine 
Format: MTH$JIOR longword1, longword2 
Returns: longword_unsigned, longword (unsigned), write 
only, by value 
longwordl: longword_unsigned, longword (unsigned), read 
only, by reference 
longword2:  longword_unsigned, longword (unsigned), read 
only, by reference 
MTH$AIMAX0 F-floating Maximum of N Word Parameters 
Routine 
Format: MTHS$AIMAX0 word, ... 
Returns: floating_point, F_floating, write only, by value 
word: word_signed, word (signed), read only, by 
reference 
MTH$AJMAXO | F-floating Maximum of N Longword Parameters 
Routine 
Format: MTHS$AJMAXO longword, ... 
Returns: floating_point, F_floating, write only, by value 
longword: longword_signed, longword (signed), read only, 
by reference 
MTH$IMAX0 Word Maximum of N Word Parameters Routine 
Format: MTHSIMAXO0 word, ... 
Returns: word_signed, word (signed), write only, by value 
word: word_signed, word (signed), read only, by 


reference 
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Table A-1 (Cont.) Additional MTH$ Routines 
Routine Name Entry Point Information 


MTH$JMAX0 Longword Maximum of N Longword Parameters 
Routine 
Format: MTH$JMAXO0O longword, ... 


Returns: longword_signed, longword (signed), write only, 
by value 


longword: longword_signed, longword (signed), read only, 
by reference 


MTH$AMAX1 F-floating Maximum of N F-floating Parameters 
Routine 
Format: MTHS$AMAX1 f-floating, ... 
Returns: floating_point, F_floating, write only, by value 


f-floating: floating_point, F_floating, read only, by reference 


MTH$DMAX1 D-floating Maximum of N D-floating Parameters 
Routine 
Format: MTHS$DMAX!1 d-floating, ... 
Returns: floating_point, D_floating, write only, by value 


d-floating: floating_point, D_floating, read only, by reference 


MTH$GMAX1 G-floating Maximum of N G-floating Parameters 
Routine 
Format: MTH$GMAX1 g-floating, ... 
Returns: floating point, G_floating, write only, by value 


g-floating: floating_point, G_floating, read only, by reference 


MTH$HMAX1 H-floating Maximum of N H-floating Parameters 
Routine 
Format: MTHS$SHMAX!1 h-float-max, h-floating, ... 
Returns: None 
h-float-max:  floating_point, H_floating, write only, by 
reference 
h-floating: floating_point, H_floating, read only, by 
reference 
MTH$IMAX1 Word Maximum of N F-floating Parameters 
Routine 
Format: MTHS$IMAX1 f-floating, ... 
Returns: word_signed, word (signed), write only, by value 


f-floating: floating_point, F_floating, read only, by reference 
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Routine Name 


MTH$JMAX1 


MTH$AIMINO 


MTH$AJMINO 


MTH$IMINO 


MTH$JMINO 


MTH$AMIN1 


Format: 


Returns: 


f-floating: 


Format: 
Returns: 


word: 


Format: 


Returns: 


longword: 


Format: 
Returns: 


word: 


Format: 


Returns: 


longword: 


Format: 
Returns: 


f-floating: 


Entry Point Information 


Longword Maximum of N F-floating Parameters 
Routine | 


MTHS$JMAX!] f-floating, ... 


longword_signed, longword (signed), write only, 
by value 


floating_point, F_floating, read only, by reference 


F-floating Minimum of N Word Parameters 
Routine 


MTHS$AIMINO word, ... 
floating _point, F_floating, write only, by value 


word_signed, word (signed), read only, by 
reference 


F-floating Minimum of N Longword Parameters 
Routine 


MTHS$AJMINO longword, ... 
floating_point, F_floating, write only, by value 


longword_signed, longword (signed), read only, 
by reference 


Word Minimum of N Word Parameters Routine 
MTHS$IMINO word, ... 
word_signed, word (signed), write only, by value 


word_signed, word (signed), read only, by 
reference 


Longword Minimum of N Longword Parameters 
Routine 


MTHSJMINO longword, ... 


longword_signed, longword (signed), write only, 
by value 


longword_signed, longword (signed), read only, 
by reference 


F-floating Minimum of N F-floating Parameters 
Routine 


MTH$AMIN1 f-floating, .. . 


. floating point, F_floating, write only, by value 


floating_point, F_floating, read only, by reference 
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Table A-1 (Cont.) Additional MTH$ Routines 


Routine Name 


MTH$DMIN1 


MTH$GMIN1 


MTH$HMIN1 


MTH$IMIN1 


MTH$JMIN1 


MTH$AMOD 


Format: 
Returns: 


d-floating: 


Format: 
Returns: 


g-floating: 


Format: 


Returns: 


h-float-max: 


h-floating: 


Format: 
Returns: 


f-floating: 


Format: 


Returns: 


f-floating: 


Format: 
Returns: 
dividend: 


divisor: 


Entry Point Information 


D-floating Minimum of N D-floating Parameters 
Routine 


MTHSDMIN1 d-floating, ... 
floating_point, D_floating, write only, by value 


floating_point, D_floating, read only, by reference 


G-floating Minimum of N G-floating Parameters 
Routine 


MTHS$GMIN1 g-floating, ... 
floating_point, G_floating, write only, by value 


floating_point, G_floating, read only, by reference 


H-floating Minimum of N H-floating Parameters 
Routine 


MTHS$HMIN1 h-float-max, h-floating, ... 
None 


floating_point, H_floating, write only, by 
reference 


floating point, H_floating, read only, by 
reference 


Word Minimum of N F-floating Parameters 
Routine 


MTHS$IMINI f-floating, .. . 
word_signed, word (signed), write only, by value 


floating_point, F_floating, read only, by reference 


Longword Minimum of N F-floating Parameters 
Routine 


MTH$JMIN1 f-floating, ... 


longword_signed, longword (signed), write only, 
by value 


floating_point, F_floating, read only, by reference 


Remainder from Division of Two F-floating 
Parameters Routine 


MTH$AMOD dividend, divisor 
floating_point, F_floating, write only, by value 
floating_point, F_floating, read only, by reference 


floating_point, F_floating, read only, by reference 
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Routine Name 


MTH$DMOD 


MTH$GMOD 


MTH$HMOD 


MTH$IMOD 


MTH$JMOD 


Format: 


Returns: 


dividend: 


divisor: 


Format: 


Returns: 


dividend: 


divisor: 


Format: 
Returns: 
h-mod: 


dividend: 


divisor: 


Format: 


Returns: 


dividend: 


divisor: 


Format: 


Returns: 


dividend: 


divisor: 


Entry Point Information 


Remainder from Division of Two D-floating 
Parameters Routine 


MTHSDMOD dividend, divisor 
floating_point, D_floating, write only, by value 
floating_point, D_floating, read only, by reference 


floating_point, D_floating, read only, by reference 


Remainder from Division of Two G-floating 
Parameters Routine 


MTH$GMOD dividend, divisor 
floating_point, G_floating, write only, by value 
floating_point, G_floating, read only, by reference 


floating point, G_floating, read only, by reference 


Remainder from Division of Two H-floating 
Parameters Routine 


MTH$HMOD h-mod, dividend, divisor 
None 


floating_point, H_floating, write only, by 
reference 


floating point, H_floating, read only, by 
reference 


floating_point, H_floating, read only, by 
reference 


Remainder from Division of Two Word 
Parameters Routine 


MTHSIMOD dividend, divisor 
word_signed, word (signed), write only, by value 


word_signed, word (signed), read only, by 
reference 


word_signed, word (signed), read only, by 
reference 


Remainder of Two Longword Parameters Routine 
MTHS$JMOD dividend, divisor 


longword_signed, longword (signed), write only, 
by value 


longword_signed, longword (signed), read only, 
by reference 


longword_signed, longword (signed), read only, 
by reference 
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Table A-1 (Cont.) Additional MTHS$ Routines 


Routine Name 


MTH$ANINT 


MTH$DNINT 


MTH$IIDNNT 


MTH$JIDNNT 


MTH$GNINT 


MTH$IIGNNT 


Format: 
Returns: 


f-floating: 


Format: 


Returns: 


d-floating: 


Format: 


Returns: 


d-floating: 


Format: 


Returns: 


d-floating: 


Format: 


Returns: 


g-floating: 


Format: 


Returns: 


g-floating: 


Entry Point Information 


Convert F-floating to Nearest F-floating Integer 
Routine 


MTHS$ANINT f-floating 
floating_point, F_floating, write only, by value 


floating_point, F_floating, read only, by reference 


Convert D-floating to Nearest D-floating Integer 
Routine 


MTHS$DNINT d-floating 
floating_point, D_floating, write only, by value 


floating_point, D_floating, read only, by reference 


Convert D-floating to Nearest Word Integer 
Routine 


MTHS$IIDNNT d-floating 
word_signed, word (signed), write only, by value 


floating_point, D_floating, read only, by reference 


Convert D-floating to Nearest Longword Integer 
Routine 


MTHS$JIDNNT d-floating 


longword_signed, longword (signed), write only, 
by value 


floating_point, D_floating, read only, by reference 


Convert G-floating to Nearest G-floating Integer 
Routine 


MTH$GNINT ¢-floating | 
floating_point, G_floating, write only, by value 


floating_point, G_floating, read only, by reference 


Convert G-floating to Nearest Word Integer — 
Routine 


MTHS$IIGNNT ¢-floating 
word_signed, word (signed), write only, by value 
floating_point, G_floating, read only, by reference 
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Routine Name 
MTH$JIGNNT 


Format: 


Returns: 
g-floating: 
MTH$HNINT 


Format: 


Returns: 


nearst-h-fit: 


h-floating: 


MTH$HNHNNT 


Format: 
Returns: 
h-floating: 


MTH$JIHNNT 


Format: 


Returns: 


h-floating: 


MTH$ININT 


Format: 
Returns: 


f-floating: 


MTH$JNINT 


Format: 


Returns: 


f-floating: 


Entry Point Information 


Convert G-floating to Nearest Longword Integer 
Routine 


MTH$JIGNNT ¢g-floating 


longword_signed, longword (signed), write only, 
by value 


floating point, G_floating, read only, by reference 


Convert H-floating to Nearest H-floating Integer 
Routine 


MTHS$HNINT nearst-h-fit, h-floating 
None 


floating_point, H_floating, write only, by 
reference 


floating_point, H_floating, read only, by 
reference 


Convert H-floating to Nearest Word Integer 
Routine 


MTHSITHNNT bh-floating 
word_signed, word (signed), write only, by value 


floating point, H_floating, read only, by 
reference 


Convert H-floating to Nearest Longword Integer 
Routine 


MTH$JIHNNT h-floating 


longword_signed, longword (signed), write only, 
by value 


floating_point, H_floating, read only, by 
reference 


Convert F-floating to Nearest Word Integer 
Routine 


MTHSININT f-floating 
word_signed, word (signed), write only, by value 


floating point, F_floating, read only, by reference 


Convert F-floating to Nearest Longword Integer 
Routine 


MTHS$JNINT f-floating 


longword_signed, longword (signed), write only, 
by value 


floating point, F_floating, read only, by reference 


(continued on next page) 
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Additional MTH$ Routines 


Table A-1 (Cont.) Additional MTH$ Routines 


Routine Name Entry Point Information 


A-16 


MTH$INOT Bitwise Complement of Word Parameter Routine 
Format: MTHS$INOT word 
Returns: word_unsigned, word (unsigned), write only, by 
value 
word: word_unsigned, word (unsigned), read only, by 
reference 
MTH$JNOT Bitwise Complement of Longword Parameter 
Routine 
Format: MTH$JNOT longword 
Returns: longword_unsigned, longword (unsigned), write 
only, by value 
longword: longword_unsigned, longword (unsigned), read 
only, by reference 
MTH$DPROD D-floating Product of Two F-floating Parameters 
Routine 
Format: MTHSDPROD f-floating1, f-floating2 
Returns: floating_point, D_floating, write only, by value 
f-floating1: floating_point, F_floating, read only, by reference 
f-floating2: floating_point, F_floating, read only, by reference 
MTH$GPROD G-floating Product of Two F-floating Parameters 
Routine 
Format: MTH$GPROD f-floating1, f-floating2 
Returns: floating_point, G_floating, write only, by value 
f-floating1: floating_point, F_floating, read only, by reference 
f-floating2: floating_point, F_floating, read only, by reference 
MTH$SGN F-floating Sign Function 
Format: MTH$SGN f-floating 
Returns: longword_signed, longword (signed), write only, 
by reference 
f-floating: floating_point, F_floating, read only, by reference 
MTH$SGN D-floating Sign Function 
Format: MTH$SGN d-floating 
Returns: longword_signed, longword (signed), write only, 
by reference 
floating point, D_floating, read only, by reference 


d-floating: 


(continued on next page) 
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Table A-1 (Cont.) Additional MTH$ Routines 


Routine Name 


MTH$IISHFT 


MTH$JISHFT 


MTH$SIGN 


MTH$DSIGN 


MTH$GSIGN 


Format: 


Returns: 


word: 


shift-cnt: 


Format: 


Returns: 


longword: 


shift-cnt: 


Format: 

Returns: 
f-float-x: 
f-float-y: 


Format: 

Returns: 
d-float-x: 
d-float-y: 


Format: 

Returns: 
g-float-x: 
g-float-y: 


Entry Point Information 


Bitwise Shift of Word Routine 
MTHS$IISHFT word, shift-cnt 


word_unsigned, word (unsigned), write only, by 
value 


word_unsigned, word (unsigned), read only, by 
reference 


word_signed, word (signed), read only, by 
reference 


Bitwise Shift of Longword Routine 
MTHS$JISHFT longword, shift-cnt 


longword_unsigned, longword (unsigned), write 
only, by value 7 


longword_unsigned, longword (unsigned), read 
only, by reference 


longword_signed, longword (signed), read only, 
by reference 


F-floating Transfer of Sign of Y to Sign of X 
Routine 


MTHS$SIGN f-float-x, f-float-y 
floating point, F_floating, write only, by value 
floating_point, F_floating, read only, by reference 


floating_point, F_floating, read only, by reference 


D-floating Transfer of Sign of Y to Sign of X 
Routine | 


MTHS$DSIGN d-float-x, d-float-y 
floating _point, D_floating, write only, by value 
floating_point, D_floating, read only, by reference 


floating_point, D_floating, read only, by reference 


G-floating Transfer of Sign of Y to Sign of X 
Routine 


MTHS$GSIGN ¢g-float-x, g-float-y 

floating_point, G_floating, write only, by value 
floating_point, G_floating, read only, by reference 
floating_point, G_floating, read only, by reference 
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Additional MTH$ Routines 


Table A—1 (Cont.) Additional MTH$ Routines 


Routine Name Entry Point Information 
MTH$HSIGN H-floating Transfer of Sign of Y to Sign of X 
Routine 
Format: MTHS$HSIGN h-result, h-float-x, h-float-y 
Returns: None 
h-result: floating point, H_floating, write only, by 
reference 
h-float-x: floating_point, H_floating, read only, by 
reference 
h-float-y: floating _point, H_floating, read only, by 
reference 
MTH$IISIGN Word Transfer of Sign of Y to Sign of X Routine 
Format: MTHSIISIGN word-x, word-y 
Returns: word_signed, word (signed), write only, by value 
word-x: word_signed, word (signed), read only, by 
reference 
word-y: word_signed, word (signed), read only, by 
reference 
MTH$JISIGN Longword Transfer of Sign of Y to Sign of X 
Routine 
Format: MTHSJISIGN longwrd-x, longwrd-y 
Returns: longword_signed, longword (signed), write only, 


by reference 


longwrd-x: longword_signed, longword (signed), read only, 
by reference 


longwrd-y: longword_signed, longword (signed), read only, 
by reference 


MTH$SNGL Convert D-floating to F-floating (Rounded) 
Routine 
Format: MTH$SNGL d-floating 
Returns: floating point, F_floating, write only, by value 


d-floating: floating_point, D_floating, read only, by reference 


MTH$SNGLG Convert G-floating to F-floating (Rounded) 
Routine 
Format: MTHSSNGLG ¢g-floating 
Returns: floating point, F_floating, write only, by value 


g-floating: floating_point, G_floating, read only, by reference 
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Table B—1 


Scalar 
Name 


AINT 
DINT 
GINT 
DPROD 
GPROD 
ACOS 
DACOS 
GACOS 
ACOSD 
DACOSD 
GACOSD 
ASIN 
DASIN 
GASIN 
ASIND 
DASIND 
GASIND 
ATAN 
DATAN 
GATAN 
ATAND 
DATAND 
GATAND 
ATAN2 
DATAN2 


B 





Vector MTH$ Routine Entry Points 


Table B-1 contains all of the vector MTH$ routines that you can call from 
VAX MACRO. Be sure to read Section 2.3.3 and Section 2.3.4 before using the 
information in this table. 


Vector MTHS Routines 


Call Vector 

or Vector Input Output Vector Name Vector Name 
JSB Registers Registers (Underflows Not Signaled) (Underflows Signaled) 
JSB vo Vo MTH$VAINT_RO_V1 

JSB VO vo MTH$VDINT_R3_V3 
JSB Vo Vo MTH$VGINT_R3_V3 
Call vVo,V1 vo MTH$VVDPROD_R1_V1 
Call V0,V1 Vo MTH$VVGPROD_R1_V1 
JSB VO Vo MTH$VACOS_R6_V7 
JSB Vo vo MTH$VDACOS_R2_V7 
JSB Vo Vo MTH$VGACOS_R2_V7 
JSB vo Vo MTH$VACOSD_R6_V7 
JSB VO vo MTH$VDACOSD_R2_V7 
JSB VO vo MTH$VGACOS_R2_V7 
JSB VO Vo MTH$VASIN_R2_V6 

JSB VO vo MTH$VDASIN_R2_V6 
JSB vo Vo MTH$VGASIN_R2_V6 
JSB VO Vo MTH$VASIND_R2_V6 
JSB Vo VO MTH$VDASIND_R2_V6 
JSB VO Vo MTH$VGASIND_R2_V6 
JSB VO Vo MTH$VATAN_RO_V4 
JSB VO VO MTH$VDATAN_RO_V6 
JSB VO Vo MTH$VGATAN_RO_V6 
JSB VO VO MTH$VATAND_RO_V4 
JSB Vo vo MTH$VDATAND_R0O_V6 
JSB VO Vo MTH$VGATAND_RO_V6 
JSB vo,v1 VO MTH$VVATAN2_R4_V7 
JSB V0,V1 Vo MTH$VVDATAN2_R4_V9 


(continued on next page) 
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Vector MTH$ Routine Entry Points 


Table B-1 (Cont.) Vector MTH$ Routines 


Call Vector 
Scalar or Vector Input Output Vector Name Vector Name 
Name JSB Registers Registers (Underflows Not Signaled) (Underflows Signaled) 
GATAN2 JSB V0O,V1 Vo MTH$VVGATAN2_R4_V9 
ATAND2 JSB V0,V1 V0 MTH$VVATAND2_R4_V7 
DATAND2 JSB VO,V1 vo MTH$VVDATAND2_R4_V9 
GATAND2 JSB vVo,V1 Vo MTH$VVGATAND2_R4_V9 
CABS Call VO,V1 vo MTH$VCABS_R1_V5 
CDABS Call V0,V1 Vo MTH$VCDABS_R1_V6 
CGABS Call V0,V1 VO MTH$VCGABS_R1_V6 
CCOS Call V0,V1 V0,V1 MTH$VCCOS_R1_V11 
CDCOS Call V0,V1 V0,V1 MTH$VCDCOS_R1_V11 
CGCOS Call Vo,vV1 V0,V1 MTH$VCGCOS_R1_V11 
COS JSB vo vo MTH$VCOS_R4_V7 
DCOS JSB vo vo MTH$VDCOS_R4_V8 
GCOS JSB Vo VO MTH$VGCOS_R4_V8 
COSD JSB vo vo MTH$VCOSD_R4_V6 
DCOSD JSB Vo Vo MTH$VDCOSD_R4_V6 
GCOSD JSB Vo vo MTH$VGCOSD_R4_V6 
CEXP Call Vo,V1 vo,V1 MTH$VCEXP_R1_V8 
CDEXP Call Vo,V1 VOo,V1 MTH$VCDEXP_R1_V10 
CGEXP Call vo,V1 vo,V1 MTH$VCGEXP_R1_V10 
CLOG Call VO0,V1 VO0,V1 MTH$VCLOG_R1_V8 
CDLOG Call Vo,V1 VO0,V1 MTH$VCDLOG_R1_V10 
CGLOG Call V0,V1 V0,V1 MTH$VCGLOG_R1_V10 
AMOD JSB V0,RO Vo MTH$VAMOD_R4_V5 MTH$VAMOD_E_R4_V5 
DMOD JSB V0,RO0 vo MTH$VDMOD_R7_V6 MTH$VDMOD_E_R7_V6 
GMOD JSB V0,RO vo MTH$VGMOD_R7_V6 MTH$VGMOD_E_R7_V6 
CSIN Call vo,V1 vo,V1 MTH$VCSIN_R1_V11 
CDSIN Call vo,V1 vVOo,V1 MTH$VCDSIN_R1_V11 
CGSIN Call vV0,V1 vVo,V1 MTH$VCGSIN_R1_V11 
CSQRT Call vo,V1 V0,V1 MTH$VCSQRT_R1_V7 
CDSQRT Call VOo,V1 V0,V1 MTH$VCDSQRT_R1_V8 
CGSQRT Call VO,V1 Vo,V1 MTH$VCGSQRT_R1_V8 
COSH JSB Vo vo MTH$VCOSH_R5_V8 
DCOSH JSB Vo vo MTH$VDCOSH_R5_V8 
GCOSH JSB Vo vo MTH$VGCOSH_R5_V8 
EXP JSB vo vo MTH$VEXP_R3_V6 MTH$VEXP_E_R3_V6 
DEXP JSB Vo VO MTH$VDEXP_R3_V6 MTH$VDEXP_E_R3_V6 
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Scalar 
Name 
GEXP 
ALOG 
DLOG 
GLOG 
ALOG10 
DLOG10 
GLOG10 
ALOG2 
DLOG2 
GLOG2 
RANDOM 
SIN 
DSIN 
GSIN 
SIND 
DSIND 
GSIND 
SINCOS 
DSINCOS 
GSINCOS 
SINCOSD 
DSINCOSD 
GSINCOSD 
SINH 
DSINH 
GSINH 
SQRT 
DSQRT 
GSQRT 
TAN 
DTAN 
GTAN 
TAND 
DTAND 
GTAND 
TANH 


Call 
or 

JSB 
JSB 
JSB 
JOB 
JSB 
JOB 
JOB 
JSB 
JSB 
JSB 
JSB 
JOB 
JSB 
JSB 
JSB 
JSB 
JOB 
JOB 
JOB 
JSB 
JSB 
JSB 
JSB 
JSB 
JSB 
JOB 
JSB 
JSB 
JSB 
JSB 
JSB 
JSB 
JSB 
JSB 
JSB 
JSB 
JSB 


Vector Input 
Registers 


VO 
VO 


vo 


VO 
Vo 
Vo 
Vo 
VO 
VO 
VO 
VO 
Vo 
Vo 
VO 
VO 
VO 
VO 
VO 
VO 
Vo 
VO 
VO 
Vo 
VO 
VO 
Vo 
VO 
VO 
Vo 
VO 
VO 
V0 
VO 
Vo 
Vo 
VO 


Vector 
Output 
Registers 
vo 


vo 


Vo 


Vo 
vo 
vo 
VO 
VO 
VO 
VO 
VO 
VO 
Vo 
VO 
Vo 
VO 
vo 
V0,V1 
V0,V1 
VO0,V1 
vo,V1 
V0,V1 
V0,V1 
vo 
Vo 
VO 
VO 
Vo 
VO 
VO 
VO 
VO 
VO 
VO 
Vo 
vo 


Vector MTH$ Routine Entry Points 


Vector Name 
(Underflows Not Signaled) 
MTH$VGEXP_R3_V6 
MTH$VALOG_R3_V5 
MTH$VDLOG_R3_V7 
MTH$VGLOG_R3_V7 
MTH$VALOG10_R3_V5 
MTH$VDLOG10_R3_V7 
MTH$VGLOG10_R3_V7 
MTH$VALOG2_R3_V5 
MTH$VDLOG2_R3_V7 
MTH$VGLOG2_R3_V7 
MTH$VRANDOM_R2_V0 
MTH$VSIN_R4_V6 
MTH$VDSIN_R4_V8 
MTH$VGSIN_R4_V8 
MTH$VSIND_R4_V6 
MTH$VDSIND_R4_V6 
MTH$VGSIND_R4_V6 
MTH$VSINCOS_R4_V7 
MTH$VDSINCOS_R4_V8 
MTH$VGSINCOS_R4_V8 
MTH$VSINCOSD_R4_V6 
MTH$VDSINCOSD_R4_V7 
MTH$VGSINCOSD_R4_V7 
MTH$VSINH_R5_V9 
MTH$VDSINH_R5_V9 
MTH$VGSINH_R5_V9 
MTH$VSQRT_R2_V4 
MTH$VDSQRT_R2_V5 
MTH$VGSQRT_R2_V5 
MTH$VTAN_R4_V5 
MTH$VDTAN_R4_V5 
MTH$VGTAN_R4_V5 
MTH$VTAND_R4_V5 
MTH$VDTAND_R4_V5 
MTH$VGTAND_R4_V5 
MTH$VTANH_R3_V10 


Vector Name 
(Underflows Signaled) 


MTH$VGEXP_E_R3_V6 


MTH$VSIND_E_R6_V6 
MTH$VDSIND_E_R6_V6 
MTH$VGSIND_E_R6_V6 


MTH$VSINCOSD_E_R6_V6 
MTH$VDSINCOSD_E_R6_V7 
MTH$VGSINCOSD_E_R6_V7 


MTH$VTAND_E_R4_V5 
MTH$VDTAND_E_R4_V5 
MTH$VGTAND_E_R4_V5 
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Table B—1 (Cont.) Vector MTH$ Routines 


Vector Name 
(Underflows Signaled) 


Vector Name 
(Underflows Not Signaled) 
MTH$VDTANH_R3_V10 
MTH$VGTANH_R3_V10 
OTS$VVDIVC_R1_V6 
OTS$VVDIVCD_R1_V7 
OTS$VVDIVCG_R1_V7 
OTS$VVMULC_R1_V4 
OTS$VVMULCD_R1_V4 
OTS$VVMULCG_R1_V4 
OTS$VPOWJJ_R1_V1 


Call Vector 
Scalar or Vector Input Output 
Name JSB Registers Registers 
DTANH JSB Vo vo 
GTANH JSB vo vo 
DIVC Call V0,V1,V2,V3 ~—~+V0~,V1 
DIVCD Call V0,V1,V2,V3_ —~-V0~,V1 
DIVCG Call V0,V1,V2,V3. —~-VO0~,V1 
MULC Call V0,V1,V2,V3 + V0,V1 
MULCD Call V0,V1,V2,V3 =~V0,V1 
MULCG Call V0,V1,V2,V3_ ~==-V0,V1 
POWJJ Call V0,RO VO 
POWRJ Call V0,RO vo 
POWDJ Call V0,RO vo 
POWGJ Call V0,RO vo 
POWRR Call VO,RO Vo 
POWDD Call VO0,RO Vo 
POWGG Call VO0,RO Vo 


R—A 


- OTS$VPOWRJ_R1_V2 


OTS$VPOWDJ_R1_V2 
OTS$VPOWGJ_R1_V2 
OTS$VPOWRR_R1_V4 
OTS$VPOWDD_R1_V8 
OTS$VPOWGG_R1_V9 


OTS$VPOWRJ_E_R1_V2 
OTS$VPOWDJ_E_R1_V2 
OTS$VPOWGJ_E_R1_V2 
OTS$VPOWRR_E_R1_V4 
OTS$VPOWDD_E_R1_V8 
OTS$VPOWGG_E_R1_V9 


A 


Absolute value, 1—4 
of complex number, MTH-—23 
Additional routines 
list of, 1-4 to 1-9 
Algorithm, 1-3 
Arc cosine 
in degrees, MTH-—6, MTH—70 
in radians, MTH-3, MTH-68 
Arce sine 
in degrees, MTH-11, MTH-74 
in radians, MTH-9, MTH-—72 
Arc tangent 
hyperbolic, MTH-21, MTH-84 
in degrees, MTH-15, MTH-19, MTH-78, 
MTH-82 
in radians, MTH-13, MTH-17, MTH-76, 
MTH-—80 
Arrays 
conversion of, MTH-63 


B 


Backward indexing, 2-6 

Bitwise AND operator, 1-4 

Bitwise complement operator, 1-8 

Bitwise exclusive OR operator, 1-5 

Bitwise inclusive OR operator, 1-6 

Bitwise shift, 1-8 

BLAS 
definition of, 2-1 

BLAS Level 1 
BLAS1$VIxAMAX, MTH-149 
BLAS1$VxASUM, MTH-152 
BLAS1$VxAXPY, MTH-155 
BLAS1$VxCOPY, MTH-160 
BLAS1$VxDOT, MTH-165 
BLAS1$VxNRM2, MTH-170 
BLAS1$VxROT, MTH-173 
BLAS1$VxROTG, MTH-178 
BLAS1$VxSCAL, MTH-182 
BLASI$VxSWAP, MTH-186 


index 


C 


Calling convention, 1-2 
Complex numbers, 1-3, MTH-56, MTH-58, 
MTH-111, MTH-121 
absolute value of, MTH-23 
complex exponential of, MTH-30, MTH-382 
conjugate of, MTH-43, MTH—44 
cosine of, MTH-26, MTH-28 
made from floating-point, MTH-39, MTH-41 
natural logarithm of, MTH-34, MTH-36 
sine of, MTH-52, MTH-53 
Condition handling, 1-3 
Conjugate of complex number, MTH-43, MTH—44 
Conversion of double to single floating-point value, 
1-9 
Conversion to greatest floating-point integer, 1-5 
Copying 
vector, MTH—160 
Cosind | 
in radians, MTH-125 
Cosine 
hyperbolic, MTH-50, MTH-88 
in degrees, MTH-48, MTH-87, MTH-128 
in radians, MTH-46, MTH-—86 
of complex number, MTH~26, MTH-28 


D 


Double-precision value 
converting, MTH-61 
converting an array of, MTH-63 


E 


Entry point name, 1-1 
Error checking 
in FOLR routines, 2-6 
Euclidean norm 
of a vector, MTH-170 
Exceptions 
recovering from, 2-7 
Exponential, MTH-65, MTH-90 
of complex number, MTH-30, MTH-32 
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F 


F-floating conversion, 1—4 
First Order Linear Recurrence, MTH-—190, 
MTH-194, MTH—-198, MTH-—202 
Floating-point 
conversion to nearest value, 1-7 
multiplication, 1-8 
positive difference, 1-5 
sign function, 1-8 
FOLR 
definition of, 2-6 
FOLR routines, MTH-190, MTH-194, MTH-198, 
MTH-202 
error checking, 2—6 
naming conventions, 2-6 
FORTRAN 
/BLAS qualifier, 2-2 
Forward indexing, 2-6 


G 


Givens plane rotation 
applying to a vector, MTH-173 
generating the elements for, MTH-178 


H 


Hyperbolic arc tangent, MTH-21, MTH-84 
Hyperbolic cosine, MTH-50, MTH-88 
Hyperbolic sine, MTH-101, MTH-133 
Hyperbolic tangent, MTH-109, MTH-142 


Index 
of a vector, MTH-—149 
Indexing 
backward, 2-6 
forward, 2—6 
Inner product 
of a vector, MTH-—165 
Integer to floating-point conversion, 1-5 


J 


JSB entry point, 1-2 


L 


Linear recurrence 
definition of, 2-6 

Logarithm 
base 2, MTH-94, MTH-115 
common, MTH-96, MTH-117 
natural, MTH-92, MTH-113 
natural complex, MTH-34, MTH-36 
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M 


Mathematics routine 
additional routines, A-1 to A-18 
Maximum value, 1-6 
Minimum value, 1-7 
MTH$ACOS, MTH-3 
MTH$ACOSD, MTH-6 
MTH$AIMAG, MTH-111 
MTH$ALOG, MTH-—113 
MTH$ALOG10, MTH-—117 
MTH$ALOG2, MTH-115 
MTH$ASIN, MTH-9 
MTH$ASIND, MTH-11 
MTH$ATAN, MTH-13 
MTH$ATAN2, MTH-17 
MTH$ATAND, MTH-15 
MTH$ATAND2, MTH-19 
MTH$ATANH, MTH-21 
MTH$CABS, MTH-23 
MTH$CCOS, MTH-26 
MTH$CDABS, MTH-23 
MTH$CDCOS, MTH-28 
MTH$CDEXP, MTH-32 
MTH$CDLOG, MTH-36 
MTH$CDSIN, MTH-53 
MTH$CDSQRT, MTH-58 
MTH$CEXP, MTH-30 
MTH$CGABS, MTH-23 
MTH$CGCOS, MTH-28 
MTH$CGEXP, MTH-32 
MTH$CGLOG, MTH-36 
MTH$CGSIN, MTH-53 
MTH$CGSQRT, MTH-58 
MTH$CLOG, MTH-34 
MTH$CMPLX, MTH-39 
MTH$CONJG, MTH-43 
MTH$COS, MTH-46 
MTH$COSD, MTH-48 
MTH$COSH, MTH-50 
MTH$CSIN, MTH-52 
MTH$CSQRT, MTH-56 
MTH$CVT_DA_GA, MTH-63 
MTH$CVT_D_G, MTH-61 
MTH$CVT_GA_DA, MTH-63 
MTH$CVT_G_D, MTH-61 
MTH$DACOS, MTH-3 
MTH$DACOSD, MTH-6 
MTH$DASIN, MTH-9 
MTH$DASIND, MTH-11 
MTH$DATAN, MTH-13 
MTH$DATAN2, MTH-17 
MTH$DATAND, MTH-15 
MTH$DATAND2, MTH-19 
MTH$DATANH, MTH-21 


MTH$DCMPLX, MTH-41 
MTH$DCONJG, MTH—44 
MTH$DCOS, MTH-46 
MTH$DCOSD, MTH-48 
MTH$DCOSH, MTH-50 
MTH$DEXP, MTH-65 
MTH$DIMAG, MTH-111 
MTH$DLOG, MTH-113 
MTH$DLOG10, MTH-117 
MTH$DLOG2, MTH-115 
MTH$DREAL, MTH-121 
MTH$DSIN, MTH-123 
MTH$DSINCOS, MTH-125 
MTH$DSINCOSD, MTH-128 
MTH$DSIND, MTH-131 
MTH$DSINH, MTH-133 
MTH$DSQRT, MTH-136 
MTH$DTAN, MTH-138 
MTH$DTAND, MTH-140 
MTH$DTANH, MTH-142 
MTH$EXP, MTH-65 
MTH$GACOS, MTH-3 
MTH$GACOSD, MTH-6 
MTH$GASIN, MTH-9 
MTH$GASIND, MTH-11 
MTH$GATAN, MTH-13 
MTH$GATAN2, MTH-17 
MTH$GATAND, MTH-15 
MTH$GATAND2, MTH-19 
MTH$GATANH, MTH-21 
MTH$GCMPLX, MTH-41 
MTH$GCONJG, MTH-44 
MTH$GCOS, MTH—-46 
MTH$GCOSD, MTH-48 
MTH$GCOSH, MTH-50 
MTH$GEXP, MTH-65 
MTH$GIMAG, MTH-111 
MTH$GLOG, MTH-113 
MTH$GLOG10, MTH-117 
MTH$GLOG2, MTH-115 
MTH$GREAL, MTH-121 
MTH$GSIN, MTH-123 
MTH$GSINCOS, MTH-125 
MTH$GSINCOSD, MTH-128 
MTH$GSIND, MTH-131 
MTH$GSINH, MTH-133 
MTH$GSQRT, MTH-136 
MTH$GTAN, MTH-138 
MTH$GTAND, MTH-140 
MTH$GTANH, MTH-142 
MTH$HACOS, MTH-68 
MTH$HACOSD, MTH-70 
MTH$HASIN, MTH-72 
MTH$HASIND, MTH-74 
MTH$HATAN, MTH-76 
MTH$HATAN2, MTH-80 


MTH$HATAND, MTH-—78 
MTH$HATAND2, MTH-82 
MTH$HATANH, MTH-84 
MTH$HCOS, MTH-86 
MTH$HCOSD, MTH-87 
MTH$HCOSH, MTH-88 
MTH$HEXP, MTH-90 
MTH$HLOG, MTH-92 
MTH$HLOG10, MTH—96 
MTH$HLOG2, MTH-94 
MTH$HSIN, MTH-98 
MTH$HSINCOS, MTH-125 
MTH$HSINCOSD, MTH-128 
MTH$HSIND, MTH-99 
MTH$HSINH, MTH-101 
MTH$HSQRT, MTH-103 
MTH$HTAN, MTH-105 
MTH$HTAND, MTH-107 
MTH$HTANH, MTH-—109 
MTH$RANDOM, MTH-119 
MTH$REAL, MTH-121 
MTH$SIN, MTH-123 
MTH$SINCOS, MTH-—125 
MTH$SINCOSD, MTH-128 
MTH$SIND, MTH-131 
MTH$SINH, MTH-133 
MTH$SQRT, MTH-—136 
MTH$TAN, MTH-138 
MTH$TAND, MTH-—140 
MTH$TANH, MTH-142 
MTH$UMAX, MTH-144 
MTH$UMIN, MTH-—145 
MTH$VxFOLRLy_MA_V5, MTH-198 
MTH$VxFOLRLy_z_V2, MTH-—202 
MTH$VxFOLRy_MA_V15, MTH-—-190 — 
MTH$VxFOLRy_z_V8, MTH-194 
Multiplying - 

vector, MTH-155 


N 


Naming conventions 
FOLR routines, 2-6 
vector routines, 2-8 
Norm 
Euclidean 
of a vector, MTH-—170 


O 


Overflow detection, 2-8 


Index—3 


P 


Plane rotation 
applying Givens plane rotation to a vector, 
MTH-173 
generating the elements for a Givens plane 
rotation, MTH-178 
Product 
of a vector, MTH-165 


R 


Random number generator, MTH-119 
Recurrence 
linear 
definition of, 2-6 
Remainder, 1-7 
Rotation 
applying to a vector, MTH-173 


S 


Scaling 
vector, MTH-182 
Sine 
hyperbolic, MTH-—101, MTH-133 
in degrees, MTH-99, MTH-—128, MTH-131 
in radians, MTH-98, MTH-123, MTH-125 
of complex number, MTH-52, MTH-53 
Square root, MTH-103, MTH-1386 
Sum of absolute values 
of a vector, MTH-152 
Swapping 
vector, MTH—-186 
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Tangent, MTH-105, MTH-107, MTH-138, 
MTH-140 
hyperbolic, MTH-109, MTH-142 
Truncation of floating-point value, 1-6 


U 


Underflow detection, 2-8 


V 


VAX FORTRAN 
/BLAS qualifier, 2-2 
VAX FORTRAN-HPO compiler, 2-2, 2-9 
Vectorization of a loop 
preventing, MTH-190, MTH-194, MTH-198, 
MTH-202 
Vectorizing FORTRAN compiler, 2-7 


Index—4 


Vector routines 
table of entry points, B—1 to B—4 
Vectors 
applying Givens plane rotation, MTH-173 
copying, MTH-160 
generating the elements for a Givens plane 
rotation, MT'H-178 
multiplying, MTH-155 
obtaining 
the Euclidean norm of, MTH—170 
the index of, MTH-149 
the inner product of, MTH-—165 
the sum of the absolute values of, 
MTH-152 
scaling, MTH-182 
swapping, MTH-186 


NOTES 


NOTES 


NOTES 


NOTES 


NOTES 


NOTES 


How to Order Additional Documentation 





Technical Support 
If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825) 
and press 2 for technical assistance. 


Electronic Orders 


If you wish to place an order through your account at the Electronic Store, dial 800-234-1998, using a 
modem set to 2400- or 9600-baud. You must be using a VT terminal or terminal emulator set at 8 bits, no 
parity. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825) and ask for an 
Electronic Store specialist. | 


Telephone and Direct Mail Orders 


From 
U.S.A. 


Puerto Rico 


Canada ~ 


International 


Internal Orders? 
(for software 
documentation) 


Internal Orders 
(for hardware 
documentation) 


Call 


DECdirect 

Phone: 800-DIGITAL 
(800-344-4825) 

FAX: (603) 884-5597 


Phone: (809) 781-0505 
FAX: (809) 749-8377 


Phone: 800-267-6215 


FAX: (613) 592-1946 


DTN: 241-3023 
(508) 874-3023 


DTN: 234-4325 
(508) 351-4325 
FAX: (508) 351-4467 


Write 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, NH 03061 


Digital Equipment Caribbean, Inc. 
3 Digital Plaza, 1st Street 

Suite 200 

Metro Office Park 

San Juan, Puerto Rico 00920 


Digital Equipment of Canada Ltd. 
100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 
Attn: DECdirect Sales 


Local Digital subsidiary or 
approved distributor 


Software Supply Business (SSB) 
Digital Equipment Corporation 
1 Digital Drive 

Westminster, MA 01473 


Publishing & Circulation Services 
Digital Equipment Corporation 
NR0O2-2 

444 Whitney Street 

Northboro, MA 01532 


1Call to request an Internal Software Order Form (EN-01740-07). 


Reader’s Comments | OpenVMS VAX RTL 
Mathematics (MTH$) Manual 





AA-PVXJA-TE 
Your comments and suggestions help us improve the quality of our publications. 
Thank you for your assistance. 
I rate this manual’s: Excellent Good Fair Poor 
Accuracy (product works as manual says) C] CJ CL) O 
Completeness (enough information) C] L L C) 
Clarity (easy to understand) | L OJ CO LJ 
Organization (structure of subject matter) L O C] LJ 
Figures (useful) CJ L] O J 
Examples (useful) LO CO L] O 
Index (ability to find topic) ‘= C] O LI 
Page layout (easy to find information) UO LI O C] 


I would like to see more/less 
What I like best about this manual is 


What I like least about this manual is 


I found the following errors in this manual: 


Page Description 








Additional comments or suggestions to improve this manual: 


For software manuals, please indicate which version of the software you are using: 


Name/Title wUW Dept. 
Company SSS C*D att“ 
Mailing Address 

Phone 
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